# The package reads itself to you

**🔵 Expert · Lesson 18**

YOU DO NOT READ A SYSTEM DOCUMENT, YOU ADDRESS IT. Four documents hang off the package root and answer AT IMPORT - before Aether boots, before a Spellbook exists, before anything is conjured.

md.__architecture__ prose, addressable by section md.__components__ prose, addressable by section md.__graph_network__ the same, PLUS a graph API md.__graph_details__ the same

`SystemGraphView` subclasses `SystemDocumentView`, so the graph documents answer every prose question too and then add nodes and edges on top.

ASK WHAT THE ADDRESS SPACE IS BEFORE YOU ADDRESS IT view.addressing -> "section" | "source_path" Keys are heading paths in one document and repository-relative file paths in another. A caller that assumes one shape silently misses in the other, so the view publishes which it is rather than making you infer it from a sample.

THE CHEAP SURVEY, THEN THE EXPENSIVE READ keys() every section key, in document order groups(depth) the index collapsed to one row per prefix index() every Section(key, start_line, end_line, line_count) find(needle) sections whose KEY matches search(needle) sections whose BODY mentions it, RANKED BY HIT COUNT, with a preview Note that `find` and `search` answer different questions - one addresses, one investigates - and neither one costs you the document. Only then: get(key) the section's text reader(key, ...) a private cursor over ONE SECTION

`reader()` TAKING A KEY IS THE WHOLE DESIGN. The paging cursor is scoped to a section, so an agent that has narrowed correctly never pages the document at all.

CITATIONS, NOT PARAPHRASES cite(key) -> "src_graph.md:3518-3596" cite(key, line=3520) -> "src_graph.md:3520" An agent can hand back an address a human can open and check. That is a different kind of answer from a summary: it is falsifiable.

REFUSED IS NOT MISSING available -> did this document ship with content reason -> why not, when it did not verify() -> re-check the shipped text against the digest its index claimed A document that fails verification still EXISTS and still answers `available` and `reason`. Omitting it would make a stale index look identical to a document that never existed - and the second one invites an agent to invent. `verify()` is ALWAYS False for an unavailable document, because there is nothing to check.

## Before you run

Use the [Expert guide](../../expert/index.md) for prerequisite concepts. Run from a checkout with Melder installed and Python 3.14 free-threading selected. The collection download includes the level's local helper modules.

## Run the saved script

```bash
python UX_and_AIX_experiences/04_expert/18_the_package_reads_itself_to_you.py
```

```powershell
py -3.14t UX_and_AIX_experiences/04_expert/18_the_package_reads_itself_to_you.py
```

{download}`Download this collection <../../downloads/expert-examples.zip>` · [Source on GitHub](https://github.com/Synaptic724/melder/blob/0895ce795453cd87e35d70665957b4e89aad3317/UX_and_AIX_experiences/04_expert/18_the_package_reads_itself_to_you.py)

## Public surface

md.__architecture__ / __components__ /
                   __graph_network__ / __graph_details__ - addressing,
                   keys, groups, index, find, search, section, get, cite,
                   reader, verify, and the graph surface

## Code

```{literalinclude} ../../downloads/04_expert/18_the_package_reads_itself_to_you.py
:language: python
:linenos:
```

## Check the outcome

The script contains its own assertions or demonstrated refusal paths. Run it to evaluate those checks against your installed version. The code above is taken directly from the saved file; no run output is invented here.

[More expert examples](index.md) · [Level guide](../../expert/index.md)

## Related guides

- [The runtime documents itself](../../expert/self-documents.md)