docs(history): document the offline reader next to codeman agent

Replace docs/offline-history.md, which repeated the skill reference and was
linked from nowhere, with a README section and a wiki section beside the
codeman agent commands. Bring the skill reference, its plugin mirror, the
Codeman Skill wiki page and the changeset in line with the reader: forks,
the separate budgets and their flags, UTC dates, phases and complete:false.

plugins/codeman/skills/codeman/reference/history.md

@@ -16,36 +16,62 @@ codeman history read --root-session-id aaaaaaaa-1111-4111-8111-111111111111 \
 
 `--session-id` accepts a native conversation UUID or unique prefix of at least
 8 characters; identity comes from metadata, not filenames. `--root-session-id`
-requires a full native UUID and includes transitive descendants found in metadata.
-The default store is `$CODEX_HOME/sessions`, or `~/.codex/sessions` when unset.
-`--file` selects one file and does not search for its ancestors or children.
+requires a full native UUID and includes transitive descendants found in metadata
+(spawned sub-agents and forks). The default store is `$CODEX_HOME/sessions`, or
+`~/.codex/sessions` when unset; a store directory that is itself a symlink is
+followed, links inside it are skipped. `--file` selects one file and does not
+search for its ancestors or children.
 
 Topic matching is a case-insensitive literal substring. Dates are inclusive
-`YYYY-MM-DD` bounds. Each filter selects whole user/assistant turns; a turn is
-retained if it has a date match and a topic match, which may be different messages
-in that turn. Tool calls/results and injected context are omitted. Adjacent duplicate
-native representations are collapsed; repeated messages from the same
-representation are retained.
+`YYYY-MM-DD` bounds compared as UTC calendar dates. Each filter selects whole
+user/assistant turns; a turn is retained if it has a date match and a topic match,
+which may be different messages in that turn. Tool calls/results and injected
+context (rows Codex adds that start with `#` or `<`, such as AGENTS.md and
+`<environment_context>`) are omitted. Adjacent duplicate native representations
+are collapsed; repeated messages from the same representation are retained.
 
-JSON is the default (`--json` or `--format json`); `--format text` is available.
+A forked or spawned thread's file starts with a copy of its parent's history. That
+copy is dropped (it is in the parent's own file), so each record belongs to the
+thread that wrote it. A later `session_meta` for any thread that is not a declared
+ancestor still refuses the file.
+
+JSON is the default (`--json` or `--format json`); `--format text` prints one block
+per record. `--json` together with `--format text` is an error.
 Results identify source paths, native session/root IDs, timestamps, roles and phases,
-plus scan counters and `complete`. A root ID is `null` when ancestry cannot be proven.
+plus scan counters and `complete`. `phase` is Codex's own (`commentary` or
+`final_answer`) on assistant records and `null` on user records or when none was
+recorded. A root ID is `null` when ancestry cannot be proven.
 Report that uncertainty; never relabel the queried child as its own root.
-`complete: false` reports malformed or partial records, skipped links, unattributed
-files or missing ancestors. It does not prove the store includes every conversation
-ever created, and a filtered result is only evidence for its selected scope.
+`complete: false` reports malformed or partial records (a running Codex may be
+mid-write), skipped links, unattributed files, unreadable directories, missing
+ancestors, or an inherited copy whose end could not be found or proven. It does not
+prove the store includes every conversation ever created, and a filtered result is
+only evidence for its selected scope.
 
 Reads require regular UTF8 files and reject final-component symlinks, conflicting
-metadata, ambiguous IDs, cyclic ancestry, invalid selectors and changed selected
-files. Directory traversal skips symlinks. Parent directories of an explicitly
-supplied path must be trusted; this is not a filesystem sandbox.
+metadata, ambiguous IDs, cyclic ancestry and invalid selectors. A store file that
+cannot be attributed (invalid UTF8 in its head, no metadata in its first 128 KiB,
+changing while its head is read) is counted in `unattributedFiles` instead of
+failing the lookup. A selected rollout that a running Codex is appending to is read
+as a snapshot up to its last complete line; one that was replaced or truncated
+fails. Parent directories of an explicitly supplied path must be trusted; this is
+not a filesystem sandbox.
 
-The default total metadata/transcript scan budget is 16 MiB; `--scan-bytes` allows
-1–67108864 bytes. Directory scans are capped at 8192 entries and depth 8. The output
-budget is 8192 bytes by default; `--max-bytes` allows 1–1048576 bytes, including the
-final newline. Exhausted budgets fail with an error: output is never silently
-truncated or split into partial JSON or turns. Narrow the store/filters or explicitly
-raise the relevant budget. Missing evidence is an error, not an empty success.
+Budgets, each failing with an error rather than a partial answer:
+
+| Flag | Bounds | Default | Maximum |
+| ---- | ------ | ------- | ------- |
+| `--metadata-bytes` | head reads attributing every rollout in the store | 1 GiB | 16 GiB |
+| `--max-entries` | directory entries visited | 65536 | 1048576 |
+| `--scan-bytes` | the selected transcripts | 16 MiB | 256 MiB |
+| `--max-bytes` | output, including the final newline | 8192 | 1048576 |
+
+Each rollout's `session_meta` carries Codex's base instructions (about 20 KiB), so
+attributing a store costs about that much per rollout, charged to
+`--metadata-bytes`, never to `--scan-bytes`. Directory depth is capped at 8 (Codex
+writes `YYYY/MM/DD`). Output is never silently truncated or split into partial
+JSON or turns. Narrow the store/filters or explicitly raise the relevant budget.
+Missing evidence is an error, not an empty success.
 
 This command does not inspect live panes, stage prompts, submit input or manage
 sessions. For live operations return to the managed-session guard in the skill.