Read Archive
Use compact discovery metadata first. Decompress exact Markdown only after
selecting the document needed for the task.
Locate the ledger
Use an explicitly supplied ledger path. Otherwise use
<workspace-root>/.agents/ledger.db; if the active workspace root is not
available, ask the user rather than guessing. Pass the database explicitly to
every command.
Discovery workflow
Browse known topics when the relevant vocabulary is unclear:
python3 <skill-root>/scripts/read.py topics \
--db <workspace-root>/.agents/ledger.db
Search titles, kinds, paths, topics, summaries, or archive dates:
python3 <skill-root>/scripts/read.py search \
--db <workspace-root>/.agents/ledger.db \
<filters>
Keep the default current-document view unless the user asks for history.
Use topics to find a shared subject. Use directed links to establish
implements, supersedes, references, or a bespoke relationship.
When exact wording or full detail is needed, select an ID and run:
python3 <skill-root>/scripts/read.py show \
--db <workspace-root>/.agents/ledger.db \
<document-id>
Answer from the verified content and cite the archived title, source path,
and document ID. Link metadata establishes relevance, not a need for payload
access; repeat show only when the additional document's exact content is
needed to answer the request.
Read references/query-model.md for filter and link
semantics.
Restore a document
Restoring writes archived Markdown back to the working tree. It never touches
SQLite.
- Identify the exact document with the discovery workflow and confirm the ID
with the user.
- Run
show for that ID. The command verifies byte length and SHA-256 before
returning, so the JSON content field is the exact archived bytes.
- Decide the destination. Default to the archived
source_path (relative paths
are under the workspace root); use a different path only when the user asks.
- If a file already exists at the destination, show that it differs and get
confirmation before overwriting. Never clobber silently.
- Write the
content string verbatim to the destination without newline
normalization or reformatting, then report the path and document ID.
Compare revisions
- Find both revisions. A
supersedes edge links a newer document to the older
one; run search --include-superseded or read the supersedes and
superseded_by links from show to get both IDs.
- Run
show for each ID and diff their verified content fields.
- Report the differences and cite both titles, source paths, and document IDs.
Failure boundary
The script is read-only. If it reports a missing or unsupported schema,
materialized VCS conflict, invalid compressed payload, byte-length mismatch, or
SHA-256 mismatch, stop and report that condition. Do not mutate the ledger,
query around the damaged row for partial source, or infer its contents.
Use the writer skill for metadata corrections or replay; this skill never
writes SQLite.
1---2name: read-archive3description: Use when a task needs to find, inspect, restore, compare, or reason from Markdown documentation previously stored in a Superstore SQLite ledger.4---56# Read Archive78Use compact discovery metadata first. Decompress exact Markdown only after9selecting the document needed for the task.1011## Locate the ledger1213Use an explicitly supplied ledger path. Otherwise use14`<workspace-root>/.agents/ledger.db`; if the active workspace root is not15available, ask the user rather than guessing. Pass the database explicitly to16every command.1718## Discovery workflow19201. Browse known topics when the relevant vocabulary is unclear:2122 ```bash23 python3 <skill-root>/scripts/read.py topics \24 --db <workspace-root>/.agents/ledger.db25 ```26272. Search titles, kinds, paths, topics, summaries, or archive dates:2829 ```bash30 python3 <skill-root>/scripts/read.py search \31 --db <workspace-root>/.agents/ledger.db \32 <filters>33 ```34353. Keep the default current-document view unless the user asks for history.364. Use topics to find a shared subject. Use directed links to establish37 `implements`, `supersedes`, `references`, or a bespoke relationship.385. When exact wording or full detail is needed, select an ID and run:3940 ```bash41 python3 <skill-root>/scripts/read.py show \42 --db <workspace-root>/.agents/ledger.db \43 <document-id>44 ```45466. Answer from the verified `content` and cite the archived title, source path,47 and document ID. Link metadata establishes relevance, not a need for payload48 access; repeat `show` only when the additional document's exact content is49 needed to answer the request.5051Read [references/query-model.md](references/query-model.md) for filter and link52semantics.5354## Restore a document5556Restoring writes archived Markdown back to the working tree. It never touches57SQLite.58591. Identify the exact document with the discovery workflow and confirm the ID60 with the user.612. Run `show` for that ID. The command verifies byte length and SHA-256 before62 returning, so the JSON `content` field is the exact archived bytes.633. Decide the destination. Default to the archived `source_path` (relative paths64 are under the workspace root); use a different path only when the user asks.654. If a file already exists at the destination, show that it differs and get66 confirmation before overwriting. Never clobber silently.675. Write the `content` string verbatim to the destination without newline68 normalization or reformatting, then report the path and document ID.6970## Compare revisions71721. Find both revisions. A `supersedes` edge links a newer document to the older73 one; run `search --include-superseded` or read the `supersedes` and74 `superseded_by` links from `show` to get both IDs.752. Run `show` for each ID and diff their verified `content` fields.763. Report the differences and cite both titles, source paths, and document IDs.7778## Failure boundary7980The script is read-only. If it reports a missing or unsupported schema,81materialized VCS conflict, invalid compressed payload, byte-length mismatch, or82SHA-256 mismatch, stop and report that condition. Do not mutate the ledger,83query around the damaged row for partial source, or infer its contents.8485Use the writer skill for metadata corrections or replay; this skill never86writes SQLite.
coltonhyer