You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2026/09/03 09:23:52 UTC
(skywalking-ai-sessionizer) 03/03: Document setup, the data formats, the guides and the 0.1.0 changes
This is an automated email from the ASF dual-hosted git repository.
wu-sheng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/skywalking-ai-sessionizer.git
commit 720568ef85e0bafe4af56dc0d2243217ddd31015
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Thu Sep 3 17:23:43 2026 +0800
Document setup, the data formats, the guides and the 0.1.0 changes
The published menu had two sections. It now follows the layout of the
other SkyWalking projects: concepts and designs, setup, data formats,
adapters, guides and changes.
Setup covers the quick start, the configuration file, every command and
the container image. Every sample is the output of one real run on
2026-09-03. Data formats describe the storage root, Session Data and
Session Flow from the code that defines them, for a third-party adapter
that produces the first and a consumer that reads the second. The guides
are contributing and how to release in the Apache way. The changes page
is what 0.1.0 contains. The status paragraphs that still said nothing
past collection existed are corrected.
---
.claude/skills/collect/SKILL.md | 14 ++-
README.md | 4 +-
docs/README.md | 18 +++-
docs/en/changes/changes-0.1.0.md | 60 ++++++++++++
docs/en/concepts-and-designs/overview.md | 5 +-
docs/en/formats/session-data.md | 100 +++++++++++++++++++
docs/en/formats/session-flow.md | 94 ++++++++++++++++++
docs/en/formats/storage-root.md | 103 ++++++++++++++++++++
docs/en/guides/contributing.md | 62 ++++++++++++
docs/en/guides/how-to-release.md | 160 +++++++++++++++++++++++++++++++
docs/en/setup/command-line.md | 133 +++++++++++++++++++++++++
docs/en/setup/configuration.md | 78 +++++++++++++++
docs/en/setup/container-image.md | 96 +++++++++++++++++++
docs/en/setup/quick-start.md | 114 ++++++++++++++++++++++
docs/menu.yml | 28 ++++++
15 files changed, 1056 insertions(+), 13 deletions(-)
diff --git a/.claude/skills/collect/SKILL.md b/.claude/skills/collect/SKILL.md
index 971b5c6..04fb264 100644
--- a/.claude/skills/collect/SKILL.md
+++ b/.claude/skills/collect/SKILL.md
@@ -102,13 +102,17 @@ thousand sources, and landing is idempotent by design.
```
<root>/<session-id>/
- session.state next_seq, liveness
- streams/main/ cursor · transcript-<ts>-<seq>.jsonl
- streams/<agent-id>/ cursor · transcript-… · meta-cursor · meta-…
- journal/<wf-id>/ cursor · journal-<ts>-<seq>.jsonl
- manifest/<run-id>/ cursor · manifest-<ts>-<seq>.jsonl
+ session.state next_seq, liveness, last scan
+ streams/main/ transcript.cursor · transcript-<ts>-<seq>.sd
+ streams/<agent-id>/ transcript.cursor · transcript-… · meta.cursor · meta-…
+ runs/<run-id>/ journal.cursor · journal-… · manifest.cursor · manifest-… · script.cursor · script-…
+ index/ entries.bin · index.state
+<root>/_conversations/<id>/rounds/r000001-<digest>.sf written by asz parse
```
+Landed files are Session Data (`.sd`), not copies of the source lines. See
+`docs/en/formats/storage-root.md`.
+
Landed files are **write-once and read-only**. Each is a header line plus one
line per source record, with the source bytes preserved verbatim in `payload`.
diff --git a/README.md b/README.md
index caffdb4..8e2d9a6 100644
--- a/README.md
+++ b/README.md
@@ -85,7 +85,9 @@ storage root copied from another machine there is no local source, so it serves
## Documentation
Official documentation lives in [`docs/`](docs/) and is indexed by
-[`docs/menu.yml`](docs/menu.yml).
+[`docs/menu.yml`](docs/menu.yml): concepts and designs, setup, the data formats, adapters, guides
+and changes. It is published at
+[skywalking.apache.org/docs/skywalking-ai-sessionizer](https://skywalking.apache.org/docs/skywalking-ai-sessionizer/next/readme/).
[`design-notes/`](design-notes/) holds working engineering notes — measurements, corrections and open
questions produced while designing against real runtime data. They are deliberately unpolished and
diff --git a/docs/README.md b/docs/README.md
index a7e7c20..d47d08d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,13 +2,21 @@
**This is the official documentation of SkyWalking AI Sessionizer. You're welcome to join us.**
-From here you can learn all about the architecture, the conversation model it builds, and how to
-collect from a supported agent runtime.
+SkyWalking AI Sessionizer assembles the fragmented telemetry of a long-lived AI agent into one
+durable conversation. It reads the files an agent runtime already writes, lands them in a format no
+runtime owns, and builds the conversation structure as a chain of immutable, verifiable rounds.
- [Concepts and Designs](en/concepts-and-designs/overview.md). Start here to understand what
- SkyWalking AI Sessionizer is and the model it assembles.
-- [Adapters](en/adapters/claude-code.md). How a specific agent runtime maps onto the model, and what
- it can and cannot supply.
+ the project is, the conversation model it assembles, and the evidence rules every page follows.
+- [Setup](en/setup/quick-start.md). Build the binary, collect this machine's history, assemble it
+ and read it. Configuration, the command line and the container image.
+- [Data Formats](en/formats/storage-root.md). What is on disk: the storage root, Session Data
+ (`.sd`) and Session Flow (`.sf`). These are public. A third-party adapter produces the first and
+ a consumer reads the second.
+- [Adapters](en/adapters/claude-code.md). How a specific agent runtime maps onto the model, and
+ what it can and cannot supply.
+- [Guides](en/guides/contributing.md). Contributing and releasing.
+- [Changes](en/changes/changes-0.1.0.md). What each version contains.
We're always looking for help improving our documentation and codebase, so please don't hesitate to
[file an issue](https://github.com/apache/skywalking-ai-sessionizer/issues/new) if you see any problem.
diff --git a/docs/en/changes/changes-0.1.0.md b/docs/en/changes/changes-0.1.0.md
new file mode 100644
index 0000000..fe0bc0d
--- /dev/null
+++ b/docs/en/changes/changes-0.1.0.md
@@ -0,0 +1,60 @@
+# Changes in 0.1.0
+
+The first release. It establishes the conversation model, one adapter that fills it from local
+Claude Code files, the two public data formats, and a local page to read the result.
+
+## Model
+
+- The Unified Conversation Model: a conversation is the durable ownership boundary whose identity is
+ supplied and never inferred; an execution stream is the ordered continuity boundary within which
+ model-message continuity is evaluated. Every word with a fixed meaning is in the glossary.
+- Evidence discipline throughout: nothing is inferred to fill a missing identifier, a reference that
+ cannot be resolved is carried as data, and content is always labelled with how much of the
+ original is present.
+
+## Collection
+
+- The `claude-code-local` adapter reads Claude Code's files from this machine: main transcripts,
+ child-agent transcripts and their sidecars, and workflow journals, manifests and scripts. It needs
+ no plugin, no hook and no configuration in Claude Code, and it works on history written before it
+ was installed.
+- Landed files are write-once, sequenced per session, and land before their cursor commits. A
+ derived index of identifiers and roles is built while landing and can be rebuilt from the landed
+ files alone.
+- Session filters by working directory, with Claude Code's own helper agents under `/private/tmp`
+ excluded by default.
+- A source reached through another filesystem, such as a bind mount into a container or a copied
+ tree, resumes where the cursor left off when its bytes are unchanged. Only truncated or rewritten
+ bytes are a conflict.
+
+## Assembly
+
+- The eight-stage pipeline: remove duplicates, partition streams, group provider calls, join
+ tools, join child agents, cut context epochs, build the conversation, and publish the delta.
+- Conversation structure is published as an append-only chain of immutable rounds. A round carries
+ no wall-clock time, so the same evidence reproduces the same bytes and digest. Absence in a later
+ round means unchanged; removal is an explicit tombstone.
+
+## Formats
+
+- Session Data, `.sd`, schema `sd/1`: the landed record, with content broken into parts named for
+ what they are and every part labelled with its state and original size.
+- Session Flow, `.sf`, schema `sf/1`: the round chain, self-verifying through commit digests and
+ bound to its evidence through a chained input digest.
+
+## Read
+
+- `asz view` serves a list of conversations and one page per conversation with its talks, its
+ execution streams, the flow on a time axis and the evidence behind every step. With the local
+ adapter it also runs the collector and the parser on the configured interval and shows the last
+ and next refresh.
+- `asz verify` checks landed data and round chains without the source files.
+
+## Tooling
+
+- One binary, `asz`, with `sources`, `collect`, `index`, `show`, `parse`, `conversation`, `view`,
+ `glossary`, `verify` and `version`.
+- A default configuration file, `asz.yaml`, read from the working directory, with every value
+ written out and held to the compiled defaults by a test.
+- A multi-platform container image on the GitHub container registry, tagged by version once a
+ release is published.
diff --git a/docs/en/concepts-and-designs/overview.md b/docs/en/concepts-and-designs/overview.md
index f742c3b..48888ef 100644
--- a/docs/en/concepts-and-designs/overview.md
+++ b/docs/en/concepts-and-designs/overview.md
@@ -42,8 +42,9 @@ never manufactured to make a tree look complete.
## Status
-Pre-alpha. The conversation model and the Claude Code data mapping are defined and evidence-backed;
-the collector, assembler, storage, export and preview are not yet implemented.
+Pre-alpha. The conversation model and the Claude Code data mapping are defined and evidence-backed.
+Collection, the derived index and assembly into a round chain are implemented. A local page that
+serves the assembled conversations is in progress. Static export and OTLP push are not started.
## Non-goals
diff --git a/docs/en/formats/session-data.md b/docs/en/formats/session-data.md
new file mode 100644
index 0000000..b340e3b
--- /dev/null
+++ b/docs/en/formats/session-data.md
@@ -0,0 +1,100 @@
+# Session Data
+
+Session Data is what was actually in a conversation, in one shape regardless of which agent
+produced it. A landed file has the extension `.sd`. Its first line is a header carrying everything
+constant for the file. Every line after it is one source record, converted, with its content broken
+into parts named for what they are: a message, a thought, a call, its result.
+
+The conversion happens once, while the source is read, and never again. A runtime's vocabulary
+stops at its adapter. A reader is handed parts, so there is no runtime shape for it to reach into.
+A dialect that meets something it cannot describe keeps the bytes verbatim in an `unknown` part
+rather than guessing or dropping them.
+
+The format is public. Package `pkg/sessiondata` defines it, and a third-party adapter produces it.
+The schema is `sd/1`.
+
+## Header
+
+```json
+{"h":1,"schema":"sd/1","seq":2,"at":"2026-09-01T12:56:03.1818Z","kind":"transcript",
+ "adapter":"claude-code-local/0.1.0","dialect":"claude-code/1",
+ "src":"-Users-me-github-skywalking/0438c73b-….jsonl","session":"0438c73b-…","stream":"main"}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `h` | envelope version, `1` |
+| `schema` | `sd/1` |
+| `seq` | the landed sequence number, monotonic per session |
+| `at` | when the file was collected |
+| `kind` | what it was collected from: `transcript`, `agent_meta`, `journal`, `workflow_manifest`, `workflow_script`, `provider_body`. `otlp_log` and `otlp_span` are reserved for a push transport. |
+| `adapter` | how the records were acquired, with its contract version |
+| `dialect` | whose schema they were read as. A push receiver and a local reader for one runtime share a dialect and nothing else. |
+| `src` | the source, relative to the adapter's root |
+| `session`, `stream`, `batch` | the session, the execution stream (`main` or an agent id), and the group of children a workflow run started |
+
+## Record
+
+```json
+{"ord":12,"off":25086,"sha":"4fed1b624096","bytes":1524,
+ "id":"c8b85d73-…","parent":"a5f0a42d-…","call":"msg_011Cdm…",
+ "from":"agent","time":"2026-08-06T16:57:22.652Z","flags":["finished"],
+ "usage":{"in":2,"out":331,"cache_read":20729,"cache_write":19709},
+ "parts":[{"k":"call","id":"toolu_015jKz…","name":"Bash","data":{"command":"make check"},
+ "state":"available","bytes":181}]}
+```
+
+Two halves. The record level carries provenance and the identifiers structure is built from, in
+role names. The part level carries what the content is.
+
+| Field | Meaning |
+| --- | --- |
+| `ord`, `off`, `sha`, `bytes` | where the record was in the source: line number, byte offset, digest of the source bytes and their size. The bytes themselves are not kept; the digest stays so provenance is provable, and a record that claims a source it did not come from is detectable. |
+| `id`, `parent` | the record's own identity and its containment parent |
+| `call` | the provider call this record is a fragment of |
+| `run` | the agent loop it belongs to, one per trigger |
+| `continues` | on a reset boundary only, the record the new context resumes from |
+| `tool`, `child`, `batch`, `started_by` | joins the runtime states outside the content: the call a sidecar answers, the child stream a record names, the group it belongs to, the stream that started this one |
+| `label` | a name the runtime gave something. The only naming evidence in the data. |
+| `from` | who produced it: `agent`, `external`, `runtime`. A record's type is not what a record is; most records that look like a person are a tool answering. |
+| `time`, `trigger`, `flags` | when, what started the loop, and states such as `finished` |
+| `usage` | what the provider reported: input, output, cache read and cache write tokens. Meaningful only where the call finished. |
+| `parts` | the content |
+| `dropped` | what the conversion chose to leave out, with its size and the reason |
+
+Empty identifiers are common and mean the runtime supplied none. Nothing is inferred to fill
+them.
+
+## Parts
+
+| Kind | Is | Carries |
+| --- | --- | --- |
+| `text` | readable text | `text` |
+| `reasoning` | the model's own reasoning | `text` when the runtime kept it |
+| `call` | a request to run something | `id`, `name`, `data` |
+| `result` | what a call returned | `of`, `text` or `data`, `failed` |
+| `media` | an image or a document | `media`, `data` |
+| `data` | structure that is not prose: a record the runtime keeps for itself, a manifest | `data` |
+| `unknown` | content the dialect could not describe | the raw bytes in `data` |
+
+Every part carries `state` and `bytes`. `state` is one of `available`, `truncated`, `redacted`,
+`omitted` or `unavailable`, and `bytes` is the size of the original even when the part holds less.
+A reader is always told how much of the original it has. One tool result in the measured corpus
+was 1.1 MB, and the share of a session that is tool output ran from 17% to 84%, so a reader is
+routinely shown part of something and has to know it.
+
+`failed` is absent, not false, when the runtime said nothing. Most results carry no error flag,
+and reading that as success would report something the runtime never claimed.
+
+The set of kinds is small because the thing described is small. Measured across a corpus of 3,032
+Claude Code files, six content shapes exist and four cover 99.99% of records.
+
+## Dropped
+
+```json
+"dropped":[{"what":"reasoning signature","bytes":588,"why":"a provider verifies it; a reader cannot read it"}]
+```
+
+`dropped` exists so a loss is stated rather than silent. It lists only what the dialect understood
+and chose not to carry. Everything it did not understand travels as an `unknown` part, so a later
+version of the dialect can interpret it without collecting again.
diff --git a/docs/en/formats/session-flow.md b/docs/en/formats/session-flow.md
new file mode 100644
index 0000000..7903fee
--- /dev/null
+++ b/docs/en/formats/session-flow.md
@@ -0,0 +1,94 @@
+# Session Flow
+
+Session Flow is the conversation structure: the talks, streams, runs, steps and relations that
+[assembly](../concepts-and-designs/conversation-assembly.md) builds from landed records. It is
+published as an append-only chain of immutable rounds. A round file has the extension `.sf`, and
+the conversation is the fold of every round. There is no other state.
+
+The format is public. Package `pkg/sessionflow` defines it, and a consumer reads it. The schema is
+`sf/1`.
+
+## A round
+
+One round is one file of JSON lines. Every line carries `t`, its frame type, and the frames come in
+a fixed order: one `header`, then any number of `node`, `relation` and `unresolved` frames, then
+one `commit`.
+
+```json
+{"t":"header","schema":"sf/1","conversation":"1213…","session":"1213…","round":1,
+ "from_seq":1,"through_seq":118,"input_digest":"48d8…","parser":"v1","policy":"v1+idle=10m0s"}
+{"t":"node","id":"ack/1/1338","revision":1,"kind":"agent.launch_ack","parent":"run/…","ref":{…}}
+{"t":"relation","id":"…","revision":1,"type":"starts","from":"…","to":"…","quality":"exact","evidence":[…]}
+{"t":"unresolved","id":"…","revision":1,"kind":"tool","ref":"toolu_…","reason":"…","state":"open"}
+{"t":"commit","digest":"d829…","counts":{"nodes":1338,"relations":52,"unresolved":0}}
+```
+
+### Header
+
+| Field | Meaning |
+| --- | --- |
+| `conversation`, `session` | the conversation this chain belongs to, and the session the round was assembled from |
+| `round` | counts from 1 |
+| `previous` | the digest of round N-1. Empty only for round 1. This is a dependency, not audit metadata: a round is built on the fold of the round it names. |
+| `from_seq`, `through_seq` | the landed sequence range this round consumed |
+| `input_digest` | binds the round to the landed evidence it read. It is chained rather than recomputed, the previous input digest hashed with the digests of the newly landed files, so producing it stays proportional to new data. |
+| `parser`, `policy` | the interpretation versions. A change to either that alters meaning starts a new chain. |
+
+A header carries no wall-clock time. A round's bytes must be reproducible from its inputs, so the
+same landed range, the same previous digest and the same parser version yield the same digest.
+When a round was produced lives outside every digest, in `conversation.state`.
+
+### Entities
+
+Nodes, relations and unresolved references share one envelope: an `id`, a `revision` and an
+optional `tombstone`. An id comes from stable evidence in the landed records, never from position,
+so an id cannot shift when an earlier source is backfilled later.
+
+| Frame | Fields |
+| --- | --- |
+| `node` | `kind`, `parent` for containment, `stream`, `ref` or `refs` pointing at the landed records that back it, and `attrs` |
+| `relation` | `type`, `from`, `to`, `quality`, `via`, and `evidence`. A typed edge that is not containment. Cross-stream flow is a relation, never containment: a child's work stays under the child. |
+| `unresolved` | `kind`, `ref`, `reason`, and `state`: `open`, `resolved` or `terminal` |
+
+A reference into the landed data is a landed sequence, a row, and optionally a content block. That
+is the whole address; a reader turns it into a moment through the index and into content through
+the `.sd` record.
+
+### Commit
+
+`digest` covers every preceding line of the file, so a round verifies itself, and it is the value
+the next round names as `previous`. `counts` lets a reader detect a truncated round without folding
+it.
+
+## The fold
+
+The conversation as of round N is the fold of rounds 1 through N, applied in order.
+
+- A frame with a higher `revision` supersedes the earlier one with the same id.
+- Absence in a later round means unchanged, never deleted. Removal is an explicit tombstone, which
+ removes the entity from the result and leaves it in history.
+- An unresolved reference that later resolves is superseded by a revision whose state says
+ `resolved`. It never vanishes, because absence never means resolved.
+- `terminal` means evidence says the reference will never resolve: a pruned source, a record the
+ runtime never wrote. It is never inferred from elapsed rounds.
+
+A round is never rewritten. Later evidence produces a new revision in a later round.
+
+## On disk
+
+```text
+_conversations/<conversation-id>/
+ conversation.state head, head digest, through_seq, input digest, parser, policy
+ rounds/r000001-<digest>.sf round number and the first twelve characters of its digest
+```
+
+The rounds directory is the authority. The state file is a cache, and a crash between publishing a
+round and saving state leaves a round the state does not mention, so the head is recovered by
+listing the directory and the previous input digest is taken from the last round's own header.
+
+## Reading it
+
+`asz conversation ID` folds a chain and prints what it holds. `asz verify` recomputes every commit
+digest. The node kinds and relation types are the vocabulary of the
+[Unified Conversation Model](../concepts-and-designs/unified-conversation-model.md), and the
+[glossary](../concepts-and-designs/glossary.md) fixes each word.
diff --git a/docs/en/formats/storage-root.md b/docs/en/formats/storage-root.md
new file mode 100644
index 0000000..c63beea
--- /dev/null
+++ b/docs/en/formats/storage-root.md
@@ -0,0 +1,103 @@
+# Storage Root
+
+The storage root is a directory. Everything the project keeps is under it, in two halves: what was
+collected, one directory per session, and what was assembled, one directory per conversation.
+
+```text
+<root>/
+ <session-id>/
+ session.state next_seq, liveness, last scan
+ .lock one collector per session
+ streams/
+ main/
+ transcript.cursor how far the source has been read
+ transcript-<collected-at>-<seq>.sd
+ <agent-id>/ one directory per child agent
+ transcript.cursor
+ transcript-<collected-at>-<seq>.sd
+ meta.cursor
+ meta-<collected-at>-<seq>.sd
+ runs/
+ <run-id>/ one directory per workflow run
+ journal.cursor · journal-…sd
+ manifest.cursor · manifest-…sd
+ script.cursor · script-…sd
+ index/
+ entries.bin the derived index
+ index.state
+ _conversations/
+ <conversation-id>/
+ conversation.state the head pointer, outside every digest
+ .lock
+ rounds/
+ r000001-<digest>.sf
+ r000002-<digest>.sf
+```
+
+Child streams are flat siblings of `main`, keyed by agent id. The storage path deliberately does
+not mirror the source tree: a path must not encode a relationship the pipeline is supposed to
+derive.
+
+## Landed files
+
+A landed file is [Session Data](session-data.md): one header line and then one record per source
+record. It is written once, to a temporary name, synced, renamed into place and made read-only.
+It is never appended to and never rewritten. A source that keeps growing produces more files, each
+starting where the previous cursor stopped.
+
+The sequence number in the name is issued per session and is monotonic across every stream in it.
+That is what lets assembly track progress with one watermark instead of one entry per stream, and
+it is why a session is collected single-threaded under its lock. The filesystem is the authority on
+the counter: on start, a collector raises its counter above the highest sequence already on disk,
+so a crash between writing a file and saving state cannot reissue a number.
+
+A file lands before its cursor is committed. A crash between the two lands the same records twice
+in the next pass, and assembly removes the duplicate. The reverse order would lose data.
+
+## The index
+
+`index/` holds identifiers and roles, never text: which record is in which stream, which call a
+fragment belongs to, which tool use a result answers, which child a launch started. Assembly reads
+this and never the payloads. It is derived and disposable. Delete it and the next collect or parse
+rebuilds it from the landed files; a schema change discards it rather than migrating it.
+
+## The chain
+
+`_conversations/<id>/rounds/` holds [Session Flow](session-flow.md): an append-only chain of
+immutable rounds. The conversation is the fold of every round; there is no other state. The file
+name carries the round number and the first twelve characters of the round's digest.
+`conversation.state` is a cache of the head. It is rebuilt by listing the directory, because a
+crash between publishing a round and saving state must not lose the round.
+
+## What travels
+
+A storage root is complete on its own. A copy of it can be listed, verified, re-parsed and read on
+another machine with no source files and no collector: the landed files name the adapter that
+wrote them, so the index rebuilds from them alone, and the chain head is recovered from the
+rounds directory. `asz verify` checks every landed file against its digest and every round against
+its commit digest without touching the source.
+
+## Size
+
+Measured on 2026-09-03 on one machine's storage root of 48 Claude Code sessions:
+
+| | Files | Size | Against the source |
+| --- | --- | --- | --- |
+| landed `.sd` | 6,615 | 800 MB | describes 1.2 GB of source records |
+| rounds `.sf` | 97 | 105 MB | 8.9% |
+| index | 48 | 52 MB | 4.5% |
+| cursors and state | 6,766 | 3 MB | |
+
+The landed data is smaller than its source because a record keeps its content and its provenance,
+not its envelope. Of the transcript content, 550 MB is carried verbatim; 64,667 reasoning parts are
+marked unavailable because Claude Code stores only a signature for them, and each record says so.
+The store had also outlived its source: it held 48 sessions where the source directory still had
+44.
+
+## Retention
+
+The session directory is the unit of retention: removing it purges everything collected for that
+session. Removing `index/` costs a rebuild. Removing a conversation's rounds loses the structure
+only; a new parse rebuilds it from the landed files, and because a round carries no wall-clock
+time, the same landed range and the same parser version reproduce the same bytes and the same
+digest.
diff --git a/docs/en/guides/contributing.md b/docs/en/guides/contributing.md
new file mode 100644
index 0000000..b8a76b2
--- /dev/null
+++ b/docs/en/guides/contributing.md
@@ -0,0 +1,62 @@
+# Contributing
+
+The project is a subproject of Apache SkyWalking. Discussion happens on the
+[dev mailing list](mailto:dev@skywalking.apache.org) and in
+[GitHub issues](https://github.com/apache/skywalking-ai-sessionizer/issues). Changes arrive as
+pull requests against `main`.
+
+## Build and test
+
+Go 1.25 or later. The module has one dependency, a YAML parser, and adding another needs a reason.
+
+```sh
+make build # -> ./bin/asz
+make test # the whole suite, with the race detector
+make test-e2e # only the end-to-end adapter tests, verbose
+make check # vet, lint, license headers, dependency licenses, tests: what CI runs
+make help # every target
+```
+
+The end-to-end suite in `tests/adapter/claudecode/local/` runs the whole pipeline over a synthetic
+fixture corpus that reproduces Claude Code's file layout byte for byte. A change to collection,
+indexing or assembly should come with a fixture that shows it.
+
+## Before opening a pull request
+
+- `make check` passes. CI runs the same targets and one required check fans them in.
+- Every source file carries the Apache license header. `make license-fix` inserts missing ones.
+- Comments, docs and commit messages are plain English. Someone reading this project is often not
+ a native English speaker, and the code is the hard part. No abbreviations, no slang, no figurative
+ words where a common one works. Short sentences, one idea each.
+- A comment says why, not what. The code already says what it does. A comment earns its place by
+ recording the reason, the measurement, or the failure that forced the choice.
+- Commit messages carry no AI attribution. The person who commits is the author, and this is an
+ Apache project whose history records people.
+
+## Evidence
+
+Every claim in the documentation is backed by a measurement against a real corpus. When changing
+the docs, keep that standard: state what was measured and on what sample, and say `unavailable`
+rather than approximating. The same rule holds in the code. The model never invents missing input,
+sessions, parentage or causal links; a reference that cannot be resolved is carried as data and
+shown as such.
+
+`design-notes/` holds the working notes: measurements, corrections and open questions, unpolished
+by intent. `docs/` is the official documentation and is published on the SkyWalking website.
+
+## Invariants
+
+The project notes in `CLAUDE.md` at the repository root list the invariants worth knowing before
+changing assembly or collector code: rounds are immutable and carry no wall-clock time, ids come
+from evidence and never from position, absence means unchanged and never deleted, landed files are
+write-once, the index is derived and disposable, and the model's vocabulary must stay free of any
+runtime's field names. Read them first.
+
+## Adding an adapter
+
+An adapter lives under `internal/adapters/<runtime>/` and produces
+[Session Data](../formats/session-data.md). It declares a glossary that maps every name the model
+can emit to the runtime's own word for it, including entries that say the runtime has no word, and
+a test fails when a name has no entry. The [Claude Code adapter](../adapters/claude-code.md) is the
+worked example, and its documentation page shows the standard: every mapping stated with its
+evidence, and every concept the runtime cannot supply said to be unavailable.
diff --git a/docs/en/guides/how-to-release.md b/docs/en/guides/how-to-release.md
new file mode 100644
index 0000000..a4900d1
--- /dev/null
+++ b/docs/en/guides/how-to-release.md
@@ -0,0 +1,160 @@
+# How to Release
+
+This guide is for the release manager, and for anyone checking a release candidate before voting.
+Apache SkyWalking AI Sessionizer follows the Apache release process: a source release is voted on
+by the SkyWalking PMC, and only after the vote passes is anything published as a release.
+
+## Prerequisites
+
+1. Close every issue in the milestone, or move what is unfinished to the next one.
+2. Write the changes page, `docs/en/changes/changes-<version>.md`, and add it to `docs/menu.yml`.
+3. Run `make check`. It includes the dependency license check.
+4. Have a GPG key. Upload its public key to a key server, add its fingerprint at
+ [id.apache.org](https://id.apache.org/), and add it to the
+ [SkyWalking KEYS file](https://dist.apache.org/repos/dist/release/skywalking/KEYS). Only a PMC
+ member can commit to that file.
+
+## Tag and build the candidate
+
+```sh
+export VERSION=0.1.0
+git clone git@github.com:apache/skywalking-ai-sessionizer.git && cd skywalking-ai-sessionizer
+git tag -a "v$VERSION" -m "Release Apache SkyWalking AI Sessionizer v$VERSION"
+git push origin "v$VERSION"
+make release VERSION=$VERSION
+```
+
+`make release` writes three files into `dist/`: the source package
+`apache-skywalking-ai-sessionizer-$VERSION-src.tgz`, its `.sha512` checksum, and its `.asc`
+signature. The package is `git archive` of the tag, so it holds exactly what is committed and
+nothing else.
+
+Pushing the tag builds the container image and publishes it under its `sha-` tag only. The
+version tags wait for the vote.
+
+## Upload the candidate
+
+```sh
+svn co https://dist.apache.org/repos/dist/dev/skywalking/ skywalking-dev
+mkdir -p skywalking-dev/ai-sessionizer/$VERSION
+cp dist/apache-skywalking-ai-sessionizer-$VERSION-src.tgz* skywalking-dev/ai-sessionizer/$VERSION/
+cd skywalking-dev/ai-sessionizer && svn add $VERSION && svn commit -m "Draft Apache SkyWalking AI Sessionizer release $VERSION"
+```
+
+## Call the vote
+
+Send to `dev@skywalking.apache.org`. Check every link before sending.
+
+```text
+Subject: [VOTE] Release Apache SkyWalking AI Sessionizer version $VERSION
+
+Hi the SkyWalking Community:
+This is a call for vote to release Apache SkyWalking AI Sessionizer version $VERSION.
+
+Release notes:
+ * https://github.com/apache/skywalking-ai-sessionizer/blob/v$VERSION/docs/en/changes/changes-$VERSION.md
+
+Release Candidate:
+ * https://dist.apache.org/repos/dist/dev/skywalking/ai-sessionizer/$VERSION
+ * sha512 checksums
+ - <sha512> apache-skywalking-ai-sessionizer-$VERSION-src.tgz
+
+Release Tag:
+ * (Git Tag) v$VERSION
+
+Release Commit Hash:
+ * https://github.com/apache/skywalking-ai-sessionizer/tree/<commit hash>
+
+Keys to verify the Release Candidate:
+ * https://dist.apache.org/repos/dist/release/skywalking/KEYS
+
+Guide to build the release from source:
+ * https://github.com/apache/skywalking-ai-sessionizer/blob/v$VERSION/docs/en/guides/how-to-release.md
+
+Voting will start now and will remain open for at least 72 hours. All PMC members are requested to give their votes.
+
+[ ] +1 Release this package.
+[ ] +0 No opinion.
+[ ] -1 Do not release this package because....
+
+Thanks.
+```
+
+## Check the candidate
+
+Everyone voting should check these before a +1:
+
+1. The source package is in the candidate directory with its `.asc` and `.sha512`.
+2. `shasum -a 512 -c apache-skywalking-ai-sessionizer-$VERSION-src.tgz.sha512` passes.
+3. `gpg --verify apache-skywalking-ai-sessionizer-$VERSION-src.tgz.asc` passes against KEYS.
+4. `LICENSE` and `NOTICE` are in the package, and every source file carries the license header.
+5. The package builds and tests from source: unpack it, then `make build && make test`.
+6. The built binary works on real data: `./bin/asz sources`, `./bin/asz collect -once`,
+ `./bin/asz parse`, `./bin/asz verify`.
+
+A PMC vote is binding. The vote passes after 72 hours with at least three binding +1 and more +1
+than -1. Send the result to the same list, listing the voters:
+
+```text
+Subject: [RESULT][VOTE] Release Apache SkyWalking AI Sessionizer version $VERSION
+
+72 hours passed, we have got (N) +1 bindings (and M +1 non-bindings):
+
++1 bindings:
+<names>
+
++1 non-bindings:
+<names>
+
+Thank you for voting, I will continue the release process.
+```
+
+## Publish
+
+1. Move the candidate to the release directory. Only a PMC member can do this.
+
+ ```sh
+ svn mv https://dist.apache.org/repos/dist/dev/skywalking/ai-sessionizer/$VERSION \
+ https://dist.apache.org/repos/dist/release/skywalking/ai-sessionizer/$VERSION \
+ -m "Release Apache SkyWalking AI Sessionizer $VERSION"
+ ```
+
+2. Publish the GitHub release for tag `v$VERSION`, with the changes page as its notes. Publishing
+ the release is what attaches the version tags to the container image: `$VERSION`, its
+ `major.minor` line, and `latest` when it is the newest release. A release that predates this
+ workflow, or a publish that failed, is promoted by running the CI workflow by hand with the tag
+ as its input.
+
+3. Update the [website](https://github.com/apache/skywalking-website): add the version and its
+ commit to the project's entry in `data/docs.yml` so the documentation is published for it, and
+ add the download link.
+
+4. Announce to `dev@skywalking.apache.org` and `announce@apache.org` from an Apache address.
+
+ ```text
+ Subject: [ANNOUNCEMENT] Apache SkyWalking AI Sessionizer $VERSION Released
+
+ Hi the SkyWalking Community,
+
+ On behalf of the SkyWalking Team, I am glad to announce that Apache SkyWalking AI Sessionizer $VERSION is now released.
+
+ SkyWalking AI Sessionizer: conversation-level observability for long-lived AI agents. It assembles fragmented agent telemetry into one durable conversation structure.
+
+ SkyWalking: APM (application performance monitor) tool for distributed systems, especially designed for microservices, cloud native and container-based architectures.
+
+ Download Links: https://skywalking.apache.org/downloads/
+ Release Notes: https://github.com/apache/skywalking-ai-sessionizer/blob/v$VERSION/docs/en/changes/changes-$VERSION.md
+ Website: https://skywalking.apache.org/
+ Documents: https://skywalking.apache.org/docs/skywalking-ai-sessionizer/v$VERSION/readme/
+
+ Resources:
+ - Issue: https://github.com/apache/skywalking/issues
+ - Mailing list: dev@skywalking.apache.org
+
+ The Apache SkyWalking Team
+ ```
+
+## Remove old releases
+
+Keep only the releases users should choose in the release directory. Older ones stay available in
+the Apache archive.
diff --git a/docs/en/setup/command-line.md b/docs/en/setup/command-line.md
new file mode 100644
index 0000000..7a94a46
--- /dev/null
+++ b/docs/en/setup/command-line.md
@@ -0,0 +1,133 @@
+# Command Line
+
+`asz` is one binary with one subcommand per step. Every command reads `asz.yaml` from the working
+directory unless `-config FILE` names another file. Commands that take a `SESSION` accept a Claude
+Code session id; a conversation `ID` is the same value, because the adapter maps one session to
+one conversation.
+
+```text
+asz sources [-config FILE] list discovered sessions and their sources
+asz collect [-config FILE] [-once] land new source data into the storage root
+asz index [-config FILE] [SESSION] report what the derived index holds
+asz show [-config FILE] SESSION ID resolve a record id or tool-use id to its payload
+asz parse [-config FILE] [SESSION] assemble conversation structure into a round chain
+asz conversation [-config FILE] ID fold a conversation's rounds and show the structure
+asz view [-config FILE] [ADDR] serve the conversations as a page
+asz glossary what the runtime calls the things the model names
+asz verify [-config FILE] [SESSION] check landed data and round chains are intact
+asz version print the version
+```
+
+## Flags
+
+| Flag | Meaning |
+| --- | --- |
+| `-config FILE` | Configuration file. Default: `./asz.yaml` when present, else the compiled defaults. |
+| `-once` | Single pass, then exit. Overrides `collector.mode`. |
+| `-terms MODE` | Name things in the model's words (`unified`, the default), the runtime's (`native`), or `both`. |
+
+## sources
+
+Discovers sessions under the source root and counts their files without landing anything. One
+row per session: directories, execution streams, child-agent sidecars, workflow journals and
+manifests. Sessions removed by the include and exclude filters are counted on the `filtered` line.
+
+## collect
+
+Lands what is new from every source into the storage root and updates the index. In watch mode it
+repeats every `interval`; with `-once` or `mode: once` it makes one pass and exits. One line per
+pass:
+
+```text
+[17:14:09] sessions=44 sources=5867 landed=5867 records=359292 bytes=1.0GB indexed=359292 gone=0 conflicts=0 busy=0 pending=0 errors=0 (2m39.473s)
+```
+
+| Field | Meaning |
+| --- | --- |
+| `sources` | source files seen this pass |
+| `landed` | sources that produced new data |
+| `records` | source records landed |
+| `indexed` | index entries across every session touched |
+| `gone` | a source deleted since the last pass. Normal: Claude Code prunes transcripts, and the landed copy outlives them. |
+| `conflicts` | a source was rotated, truncated or rewritten behind its cursor. Collection stopped for it. |
+| `busy` | a session skipped because another collector holds its lock |
+| `pending` | a source still had data when the per-pass limit was reached |
+| `errors` | listed on standard error after the line |
+
+`pending` or `errors` above zero means the pass did not collect everything, and the command exits
+non-zero. A clean pass is `pending=0 errors=0`.
+
+## index
+
+Reports the derived index of one session, or of every session: entries, joinable content blocks,
+streams and interned strings, plus a count of records by kind. The index holds identifiers and
+roles only, never text, and can be deleted; the next collect or parse rebuilds it from the landed
+files.
+
+## show
+
+Resolves one record id, or one tool-use id, to the landed record that carries it and prints the
+record. This is the way to see exactly what a step in a conversation is backed by.
+
+## parse
+
+Assembles every session, or one, and appends a round to each conversation's chain when something
+changed. One row per session:
+
+```text
+SESSION ROUND SEQ NODES RELS UNRES TALKS RUNS STEPS TOOLS CHILDREN
+0438c73b-2367-4ed5-9de3-13ef9a17ed01 1 305 17249 703 0 357 445 11473 5620/5620 131/131
+```
+
+`ROUND` is the round written, or `-` when nothing changed. `SEQ` is the landed sequence the
+conversation now covers. `UNRES` counts references that could not be resolved. `TOOLS` and
+`CHILDREN` are joined out of total. The command exits non-zero when any session failed to parse,
+so a loop or a CI step can read the status instead of the log.
+
+## conversation
+
+Folds a conversation's chain and prints the structure: rounds and head digest, the landed range,
+entity counts, and a count of nodes by kind.
+
+```text
+conversation 0438c73b-2367-4ed5-9de3-13ef9a17ed01
+ rounds 1, head 9a29d5acdd73…
+ landed through seq 305
+ entities 17249 nodes, 703 relations, 0 unresolved (0 still open)
+```
+
+## view
+
+Serves the conversations as a page on `ADDR`, `127.0.0.1:8787` by default. The list is at `/` and
+one conversation at `/c/{id}`. The page reads the folded chain on demand and caches nothing beyond
+the process.
+
+With the `claude-code-local` adapter, when its source directory exists on the machine, the same
+process also runs the collector and the parser: once with `-once`, or on the collector interval
+otherwise. `/api/status` reports the mode, the source, the last and the next refresh and the counts
+of the last pass, and the list page shows the same. On a storage root copied from another machine
+there is no source, so the page serves what is there and shows no refresh.
+
+## glossary
+
+Prints every name the model uses, what the runtime calls it, where in the runtime's records it is
+found, and a note. A `—` in the runtime column means the model derives the concept and the runtime
+has no word for it. Every command that prints names accepts `-terms native` to use the runtime's
+words instead.
+
+## verify
+
+Checks every landed file against its digest and every round against its commit digest, for one
+session or all of them. It reads the storage root only, so it works without the source files and
+without a collector.
+
+```text
+checked 44 session(s), 5867 stream(s), 359292 records
+checked 44 conversation chain(s), 44 round(s)
+all landed data is contiguous and matches its digests
+```
+
+## version
+
+Prints the version the binary was built with, the Go version, and the platform. A release build
+says its version; a plain `go build` says `dev`.
diff --git a/docs/en/setup/configuration.md b/docs/en/setup/configuration.md
new file mode 100644
index 0000000..ac5ba23
--- /dev/null
+++ b/docs/en/setup/configuration.md
@@ -0,0 +1,78 @@
+# Configuration
+
+One YAML file. Every command reads `asz.yaml` from the working directory when no `-config` flag is
+given, and `-config FILE` names another one. The file at the repository root is the default
+configuration with every value written out, and a test holds it to the compiled defaults, so
+reading that file is reading the defaults.
+
+```yaml
+storage:
+ root: ./data
+
+adapters:
+ - name: claude-code-local
+ enabled: true
+ source_root: ""
+ include: []
+ exclude:
+ - /private/tmp/**
+ collector:
+ mode: watch
+ interval: 5s
+ max_delta_bytes: 8388608
+```
+
+## storage
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `root` | `./data` | The storage root: where collected data lands and where conversations are assembled. A relative path is resolved from the working directory. |
+
+The default is ignored by git, so running the collector inside a checkout never stages private
+transcripts.
+
+## adapters
+
+A list. Version 0.1.0 has one adapter, `claude-code-local`, which reads Claude Code's files from
+this machine. Every command runs once per enabled adapter.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `name` | | `claude-code-local` |
+| `enabled` | `true` | A disabled adapter is skipped by every command. |
+| `source_root` | empty | Where Claude Code keeps its files. Empty resolves it the way Claude Code does: `CLAUDE_CONFIG_DIR`, then `XDG_CONFIG_HOME/claude`, then `~/.claude`, each followed by `projects`. Set it only to collect from a copy or a mounted directory. |
+| `include` | empty | Session filters, see below. Empty means every session is a candidate. |
+| `exclude` | `/private/tmp/**` | Session filters, see below. |
+
+### Session filters
+
+A session is judged by the working directory its main transcript was recorded under. An entry that
+starts with `/` is a working directory, and `**` after it matches everything beneath. Anything else
+is a glob matched against the source directory name as Claude Code wrote it, which is the working
+directory with every separator replaced by `-`.
+
+A session's child agents can run in other directories, so the filter looks at the main transcript
+only. A session that merely used a scratch directory for a child agent is still collected. When the
+main transcript has been pruned, the session is judged on all of its directories together and is
+excluded only when every one of them matches, so an orphaned child stream from a real project is
+still collected.
+
+Claude Code runs its own helper agents in scratch directories under `/private/tmp`. Those sessions
+are the tool's, not yours, which is why they are excluded by default.
+
+## collector
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `mode` | `watch` | `watch` polls the source continuously. `once` makes a single pass and exits, which is the backfill path over history that already exists. `-once` on the command line overrides the file. |
+| `interval` | `5s` | How long the collector sleeps between passes in watch mode. `asz view` refreshes on the same interval. |
+| `max_delta_bytes` | `8388608` | The largest landed file written from one source in one pass, 8 MiB. A large catch-up is split into several files rather than one enormous one. |
+
+## Precedence
+
+1. `-config FILE` on the command line.
+2. `./asz.yaml` in the working directory.
+3. The compiled defaults, which are the values shown above.
+
+A file may leave keys out. Anything unset takes its default, except that a file which lists
+`adapters` replaces the whole list.
diff --git a/docs/en/setup/container-image.md b/docs/en/setup/container-image.md
new file mode 100644
index 0000000..cd22b36
--- /dev/null
+++ b/docs/en/setup/container-image.md
@@ -0,0 +1,96 @@
+# Container Image
+
+CI publishes a multi-platform image, `linux/amd64` and `linux/arm64`, to the GitHub container
+registry:
+
+```text
+ghcr.io/apache/skywalking-ai-sessionizer
+```
+
+It carries the `asz` binary and nothing else. The base is distroless, there is no shell, and the
+process runs as a non-root user. Its working directory is `/asz`, so the default storage root is
+`/asz/data`, which is declared as a volume, and a configuration file placed at `/asz/asz.yaml` is
+read the same way it is on a host.
+
+## Tags
+
+| Tag | Points at | Moves |
+| --- | --- | --- |
+| `0.1.0` | that release | never |
+| `0.1` | the newest patch release of that line | on each patch |
+| `latest` | the newest release | on each release |
+| `main` | the development head | on each push to `main` |
+| `sha-<commit>` | one commit | never |
+
+A `v*` tag is a release candidate until the Apache vote has passed. Pushing one publishes only its
+`sha-` tag. The version tags are attached when the GitHub release is published, which happens after
+the vote. A pre-release version such as `0.2.0-rc1` gets its own tag and moves nothing else.
+
+Every image carries `org.opencontainers.image.version` and `org.opencontainers.image.revision`
+labels, and `asz version` inside it prints the same version.
+
+## Serve a storage root
+
+The default command serves the page on port 8787, listening on every interface because a
+container's loopback is not reachable from outside.
+
+```sh
+docker run --rm -p 8787:8787 -v "$PWD/data:/asz/data" \
+ ghcr.io/apache/skywalking-ai-sessionizer:latest
+```
+
+There is no Claude Code inside the container, so the page serves what the storage root holds and
+shows no refresh. This is the way to read a storage root that was collected elsewhere.
+
+## Collect from the host
+
+To collect inside the container, mount Claude Code's directory read-only and tell the adapter
+where it is. Put a configuration file beside the storage root:
+
+```yaml
+# asz.yaml
+storage:
+ root: /asz/data
+adapters:
+ - name: claude-code-local
+ enabled: true
+ source_root: /claude/projects
+ exclude:
+ - /private/tmp/**
+```
+
+A file that lists `adapters` replaces the whole list, so the exclude has to be repeated or Claude
+Code's own helper sessions under `/private/tmp` are collected too. Measured on one machine: 44
+sessions with the exclude, 64 without.
+
+```sh
+docker run --rm -p 8787:8787 \
+ -v "$HOME/.claude/projects:/claude/projects:ro" \
+ -v "$PWD/asz.yaml:/asz/asz.yaml:ro" \
+ -v "$PWD/data:/asz/data" \
+ ghcr.io/apache/skywalking-ai-sessionizer:latest
+```
+
+The container user is not the host user, so on Linux the storage root must be writable by it.
+Running with `--user "$(id -u):$(id -g)"` is the simplest way. Docker Desktop on macOS maps
+bind mounts for you.
+
+## Run any command
+
+Put the command after the image name. The entrypoint is the binary.
+
+```sh
+docker run --rm -v "$PWD/data:/asz/data" ghcr.io/apache/skywalking-ai-sessionizer:latest verify
+docker run --rm ghcr.io/apache/skywalking-ai-sessionizer:latest glossary
+docker run --rm ghcr.io/apache/skywalking-ai-sessionizer:latest version
+```
+
+## Build locally
+
+```sh
+make docker # -> skywalking-ai-sessionizer:dev
+```
+
+The Dockerfile cross-compiles from the build host, so a multi-platform build needs no emulation
+and no third-party action. The version is passed as a build argument; `make docker` passes the
+nearest git tag.
diff --git a/docs/en/setup/quick-start.md b/docs/en/setup/quick-start.md
new file mode 100644
index 0000000..8abe7ea
--- /dev/null
+++ b/docs/en/setup/quick-start.md
@@ -0,0 +1,114 @@
+# Quick Start
+
+This page takes a machine that has used Claude Code and turns its history into conversations you
+can read. Nothing in Claude Code changes: no plugin, no hook script, no environment variable. The
+collector reads files that are already on disk, so it also works on history written before it was
+installed.
+
+## Build
+
+Go 1.25 or later. The module has one dependency, a YAML parser.
+
+```sh
+git clone https://github.com/apache/skywalking-ai-sessionizer.git
+cd skywalking-ai-sessionizer
+make build # -> ./bin/asz
+./bin/asz version
+```
+
+Every command reads `asz.yaml` from the working directory when no `-config` flag is given. The
+file at the repository root is the default configuration with every value written out, so the
+commands below work as they are. See [Configuration](configuration.md) to change where data comes
+from or goes.
+
+## See what is there
+
+```sh
+./bin/asz sources
+```
+
+```text
+source root: /Users/me/.claude/projects
+filtered : 20 session(s) excluded by config
+
+SESSION DIRS STREAMS META JOURNAL MANIFEST
+0438c73b-2367-4ed5-9de3-13ef9a17ed01 2 132 131 14 14
+04b56e12-fae2-4413-a7c1-f18911a1463f 1 1 0 0 0
+```
+
+One row per session: how many directories its files are spread across, how many execution
+streams it has (the main transcript plus one per child agent), and how many child-agent sidecars,
+workflow journals and manifests were found. The source directory is resolved the way Claude Code
+resolves it: `CLAUDE_CONFIG_DIR`, then `XDG_CONFIG_HOME`, then `~/.claude`. Sessions under
+`/private/tmp` are Claude Code's own helper agents and are excluded by default.
+
+## Land the history
+
+```sh
+./bin/asz collect -once
+```
+
+```text
+[17:14:09] sessions=44 sources=5867 landed=5867 records=359292 bytes=1.0GB indexed=359292 gone=0 conflicts=0 busy=0 pending=0 errors=0 (2m39.473s)
+```
+
+Every source file is read from its cursor onward and written into the storage root as Session
+Data, then indexed. The line above is one machine's first pass, measured on 2026-09-03: 44
+sessions, 5,867 source files, 1.0 GB of records, in 2 minutes 39 seconds. Later passes read only
+what is new; the next pass on the same machine landed one source in 933 ms. A pass with `pending`
+or `errors` above zero did not collect everything, and the command exits non-zero so a script can
+tell. Re-running is safe: landing is idempotent by design.
+
+## Assemble
+
+```sh
+./bin/asz parse
+```
+
+```text
+SESSION ROUND SEQ NODES RELS UNRES TALKS RUNS STEPS TOOLS CHILDREN
+0438c73b-2367-4ed5-9de3-13ef9a17ed01 1 305 17249 703 0 357 445 11473 5620/5620 131/131
+04b56e12-fae2-4413-a7c1-f18911a1463f 1 1 409 11 0 11 11 277 146/146 0/0
+04c6e9de-3b81-4106-a08b-e75259c33ca4 1 1 5 0 0 0 0 2 0/0 0/0
+…
+44 round(s) written
+```
+
+Each session becomes one conversation, and each parse appends one round to its chain when
+something changed. `TOOLS` and `CHILDREN` show how many tool calls and child-agent launches were
+joined to their results, out of how many exist. A second run with nothing new writes no rounds.
+
+## Read
+
+```sh
+./bin/asz view
+```
+
+Open `http://127.0.0.1:8787`. The list page shows every conversation; a conversation page shows
+its talks, its execution streams, the flow on a time axis, and the evidence behind every step.
+
+On a machine with Claude Code, `asz view` alone is enough. It runs the collector and the parser
+itself, every 5 seconds by default, and the list page shows when the data was last refreshed and
+when it will be next. The two steps above are worth running once to see what each does.
+
+## Check
+
+```sh
+./bin/asz verify
+```
+
+```text
+checked 44 session(s), 5867 stream(s), 359292 records
+checked 44 conversation chain(s), 44 round(s)
+all landed data is contiguous and matches its digests
+```
+
+Every landed file is checked against its digest and every chain against its own commit digests.
+This needs no source files and no collector, so it also works on a storage root copied from
+another machine.
+
+## Where it went
+
+Everything is under the storage root, `./data` by default. Landed files are write-once, the index
+is derived and disposable, and the round chain is append-only. Deleting the directory starts over.
+See [Storage Root](../formats/storage-root.md).
diff --git a/docs/menu.yml b/docs/menu.yml
index 7208b73..fca19bd 100644
--- a/docs/menu.yml
+++ b/docs/menu.yml
@@ -28,9 +28,37 @@ catalog:
path: /en/concepts-and-designs/conversation-assembly
- name: Glossary
path: /en/concepts-and-designs/glossary
+ - name: Setup
+ catalog:
+ - name: Quick Start
+ path: /en/setup/quick-start
+ - name: Configuration
+ path: /en/setup/configuration
+ - name: Command Line
+ path: /en/setup/command-line
+ - name: Container Image
+ path: /en/setup/container-image
+ - name: Data Formats
+ catalog:
+ - name: Storage Root
+ path: /en/formats/storage-root
+ - name: Session Data
+ path: /en/formats/session-data
+ - name: Session Flow
+ path: /en/formats/session-flow
- name: Adapters
catalog:
- name: Claude Code
path: /en/adapters/claude-code
- name: Claude Code Glossary
path: /en/adapters/claude-code-glossary
+ - name: Guides
+ catalog:
+ - name: Contributing
+ path: /en/guides/contributing
+ - name: How to Release
+ path: /en/guides/how-to-release
+ - name: Changes
+ catalog:
+ - name: 0.1.0
+ path: /en/changes/changes-0.1.0