perga 0.1.5

A terminal Markdown browser with a persistent file tree, tabs, wiki-links and backlinks
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
# Decisions

Every ambiguity in the build specification that was resolved during implementation
is recorded here, with the rationale. Newest entries at the bottom of each
milestone section.

---

## M0 — Repository foundation

### D1: MSRV pinned to 1.95

Section 5.1 asks for "the stable release current when you start, minus two minors".
Implementation started on Rust 1.97.1, so `rust-version = "1.95"`. Verified in CI by
a dedicated `msrv` job that reads the value out of `Cargo.toml` rather than
duplicating it, so bumping the manifest bumps the CI job.

### D2: `tui-textarea` replaced with `tui-textarea-2`

Section 5.2 mandates `tui-textarea` for the editor widget. The published
`tui-textarea` 0.7.0 depends on `ratatui ^0.29`, while `tui-markdown` 0.3.9 — also
mandated — is built on `ratatui-core` 0.1.2, the 0.30 line. Holding both would put
two incompatible `ratatui` versions in the tree: the textarea widget could not be
rendered into a frame produced by the other version, and the duplicate would be
flagged by the `bans` section of `deny.toml`.

`tui-textarea-2` 0.13.2 is the maintained fork of the same crate, published under
the same `tui_textarea` library name with the same API, licensed MIT, and built on
`ratatui-core` 0.1.x. Adopting it aligns the whole tree on one `ratatui` version.
The `search` feature is enabled, since Section 9.8 says the editor's own search is
to be used rather than reimplemented.

Revisit if upstream `tui-textarea` publishes a `ratatui` 0.30 release.

### D3: `unicode-width` pinned to 0.2.0

`ratatui` pins `unicode-width = "=0.2.0"` exactly. Section 5.2 requires
`unicode-width` as a direct dependency for CJK and emoji column widths, so the
direct dependency is written as `"0.2.0"` to unify on the version `ratatui` already
carries. Section 0.7 forbids hand-writing versions to pin them; this is not a pin
for its own sake but the only version that resolves.

### D4: `tui-markdown` default features disabled

`tui-markdown`'s default feature set includes `highlight-code`, which pulls its own
`syntect` with the default `onig` backend and an `ansi-to-tui` round trip. Section
5.2 mandates `syntect` with `default-features = false, features = ["default-fancy"]`
because the `onig` backend links a C library and breaks static musl builds, and
Section 9.2 specifies perga's own code-block highlighting with a per-`(language,
content_hash)` cache. `tui-markdown` is therefore taken with
`default-features = false` and code highlighting is done by perga.

### D5: `CC0-1.0` added to the `deny.toml` licence allow list

Section 16.6 lists the permissive licences to allow and instructs that a dependency
introducing a licence outside the list be replaced rather than the list widened.
`notify`, which Section 5.2 mandates for filesystem watching, is published under
`CC0-1.0`. CC0-1.0 is a public-domain dedication — strictly more permissive than
every other entry on the list, with no attribution or reciprocity obligation — and
replacing a dependency the specification names is a larger deviation than admitting
it. The entry is annotated in `deny.toml` with the crate that requires it.

### D6: unmaintained-crate advisories scoped to direct dependencies

Section 16.6 asks cargo-deny to "deny on any RUSTSEC vulnerability, warn on
unmaintained crates". cargo-deny 0.20 expresses this with
`advisories.unmaintained`, whose values are `none`, `workspace`, `transitive`, and
`all` rather than a severity. `workspace` is used: unmaintained advisories are
reported for perga's own direct dependencies and not for crates buried inside them.

The two advisories currently suppressed by this scoping are `bincode` 1.3.3
(RUSTSEC advisory: complete, not in need of updates) and `yaml-rust` 0.4.5
(RUSTSEC-2024-0320), both reached only through `syntect`, which Section 5.2
mandates. Neither is a vulnerability; both are maintenance-status notices with no
safe upgrade available from perga's side. Vulnerability advisories remain a hard
failure at every depth.

### D7: `duplicate major version` skips

`bans.multiple-versions` is `deny`, qualified by Section 16.6's "where avoidable".
Four duplicates are not avoidable from perga: `signal-hook@0.3` (pulled by
`crossterm` 0.29, while Section 5.2 requires `signal-hook` directly, now at 0.4),
and `syn@2`, `hashbrown@0.16`, and `itertools@0.14`, all transitive build-graph
churn in the proc-macro and parser ecosystem. Each is listed in `bans.skip` with a
comment. The list is reviewed on every dependency bump and entries are removed as
upstreams catch up.

### D8: Man page and completions are not generated by `build.rs`

Section 16.5 requires this and the reasoning is recorded here for completeness:
sharing the `clap` definition with a build script means either duplicating the CLI
module or `#[path]`-including it, both of which drift. `--generate-man` and
`--generate-completions <shell>` are implemented in the binary and invoked by the
release pipeline and by every packaging artefact against the freshly built binary.

### D9: Development is happening on macOS; Linux verification is deferred

perga targets Linux only (Section 4) and the specification forbids
`#[cfg(target_os)]` branches for other platforms. The development machine available
for this work runs macOS. No macOS-specific code is being written and no
cross-platform dependency is being added for its sake, but the following cannot be
verified locally and must be confirmed by CI or by the owner on Linux:

- `x86_64-unknown-linux-musl` and `aarch64-unknown-linux-musl` static builds
  (covered by the `build` job in CI).
- inotify behaviour, including the `max_user_watches` degradation path
  (Section 9.9).
- `xdg-open` handoff for external links and non-Markdown targets (Section 9.5).
- `SIGTSTP`/`SIGCONT` suspend and resume against a Linux terminal (Section 12).

Every one of these is exercised by the Linux CI jobs, which are the authority.

---

## M1 — Terminal shell and event loop

### D10: a library target alongside the binary

Section 6 lists `src/main.rs` as the only entry point, but Section 15.3 requires
integration tests in `tests/` that drive the application by feeding it `Action`
sequences, and Section 15.2 requires snapshot tests that render to
`ratatui::backend::TestBackend`. An integration test cannot reach inside a binary
crate. `src/lib.rs` therefore exposes every module and `src/main.rs` is a thin
wrapper that owns only argument parsing, terminal setup and teardown, the panic
hook, and the worker threads. The module layout of Section 6 is otherwise
unchanged.

### D11: `Terminal::clear()` is not called during setup

`ratatui`'s `Terminal::clear` reads the cursor position back from the terminal so
it can restore it afterwards. That is a full round trip: it costs a meaningful part
of the 50 ms first-frame budget in Section 14, and on a terminal that does not
answer the query it fails outright — which is how it was found, in a pseudo-
terminal harness where startup aborted with "The cursor position could not be read
within a normal duration".

Entering the alternate screen already presents a blank screen and the first draw
paints all of it, so the call is unnecessary at startup. It is still made when
resuming from `SIGTSTP`, where the shell has genuinely written over the screen and
the frame must be repainted rather than diffed.

### D12: `terminal::setup` restores on its own failure

The first version returned the error from a partially completed setup, leaving raw
mode and the alternate screen enabled with no handle for the caller to clean up
with — the exact failure Section 13 forbids. `setup` now wraps its work and calls
`restore` before returning any error, and `main` calls `restore` on its error path
as well. `restore` is idempotent, so the overlap is harmless.

### D13: `Ctrl+C` is not remappable

Section 12 does not list `Ctrl+C`, but Section 7.3 says an overlay swallows all
input "except `Esc` (close) and `Ctrl+C` (quit)". It is therefore handled ahead of
the keymap in `event.rs` and is not in the binding table: a user who remapped it
away could otherwise be left with no way out of a wedged overlay.

### D14: the status bar and welcome screen read their keys from the keymap

Section 8.3 requires the help overlay to be generated from the keymap so it cannot
drift. The same argument applies to the two other places that show a key to the
user — the status bar hint row and the welcome screen's onboarding block — so both
look their keys up through `Keymap::binding_for` rather than hardcoding them. A
remap moves all three together.

### D15: a terminal resize does not overwrite the chosen sidebar width

Clamping `Sidebar::width` on every resize destroyed the user's choice: shrinking
the terminal to 30 columns and growing it back left the sidebar at its minimum
width for the rest of the session. The chosen width is now stored unclamped and
clamped only by the layout pass, so a temporary shrink narrows what is drawn and
widening restores it. Explicit `<` and `>` presses still clamp, because those are
the user setting a width against a terminal they can see.

### D16: panic-hook restoration is verified through a pseudo-terminal, by hand

Section 13 asks for the panic hook to be tested "by injecting a panic behind a
hidden debug flag". The flag is `--debug-panic`, hidden from `--help`. It cannot
be exercised by `cargo test`: raw mode fails without a controlling terminal, so
the assertion would pass for the wrong reason. It was verified by running the
binary under a pseudo-terminal and confirming that the alternate screen is left,
mouse capture and bracketed paste are disabled, and the cursor is shown, all
before the panic message is printed. Reproduce with:

```sh
script -q /dev/null perga --debug-panic
```

The terminal must be usable afterwards and the panic message readable.

### D17: idle CPU measured at zero

Section 14 requires 0% CPU at idle. Measured by running the release binary under a
pseudo-terminal, leaving it untouched for ten seconds, and reading accumulated CPU
time from `ps`: 0.00 seconds. This holds by construction — a dedicated input
thread and a single blocking `recv` on the main loop, with no poll timeout
anywhere — rather than by tuning.

---

## M2 — Markdown rendering pipeline

### D18: link destinations are stripped from the rendered text

`tui-markdown` renders `[label](target)` as `label (target)` and offers no
option to suppress the destination. Section 8.1 says markup is never shown in
read mode, and its layout sketch shows link labels alone. The wrapper therefore
removes the destination, which `tui-markdown` emits as a recognisable triple —
an unstyled `" ("`, the destination in the link style, an unstyled `")"`.

Nothing is lost by this: links are extracted from the *source* in M4, where they
can be resolved against the containing document's directory, which is the only
place the target can be handled correctly anyway.

### D19: code fences are not rendered

`code_block_fence` is overridden to the empty string. The fences are markup, and
the layout sketch in Section 8.1 shows a code block without them; the block's
background and its highlighting are what mark it as code.

This has a second benefit that turned out to matter more than the first: with
the fences gone, a fenced code block renders exactly one line per source line,
which is what makes the offset-to-line map *exact* inside code rather than
interpolated. Find-in-document and edit-mode cursor round-tripping both land on
the right line there as a result.

### D20: the offset-to-line map is exact in code and proportional in prose

Section 9.2 requires a bidirectional map between source byte offsets and
rendered line numbers, and Section 20 warns that five features depend on it.

Exactness is only achievable where the correspondence exists. A fenced code
block renders one line per source line, so every source line gets its own entry.
Prose is re-wrapped, so one source line may become several rendered lines and
several source lines may share one; there its source lines are distributed over
its rendered lines in proportion. Every *block boundary* is exact in both cases,
which is what anchor navigation and outline synchronisation actually need, and
the map is monotonic throughout, which is what find and link positioning need.

### D21: a blank line separates blocks

`tui-markdown` renders a block as its own lines and nothing more, so without a
separator every paragraph, heading, and list runs into the next one. The
renderer appends one blank line to each non-empty block. It lives in the block
cache rather than in the layout so that heights, the line map, and the cache all
agree on what a block's rendered height is.

### D22: task markers and image placeholders are rewritten in the wrapper

Two more places where `tui-markdown`'s output and this specification disagree,
both handled in the same adapter layer as D18:

- Section 9.2 asks for `☐`/`☑`; `tui-markdown` passes `[x]`/`[ ]` through as
  literal text, in the same span as the list bullet. Only a line's first span is
  examined, so an `[x]` written inside an item's prose is left alone.
- Section 9.2 asks for `[image: alt text]` styled with `image_placeholder`;
  `tui-markdown` writes `[img] alt text`. The rewrite is isolated in
  `render_image_placeholder`, so a future Kitty or Sixel renderer replaces that
  one function and nothing else in the pipeline.

### D23: the layout is invalidated by document content, not by block count

The first version of `RenderedDocument` reset itself when the width or the
number of blocks changed. Editing a paragraph changes neither, so the layout
happily served stale measurements — caught by the test that asserts an edit
re-renders exactly one block, which re-rendered zero. `Document` now carries a
hash of its source and the layout resets when that changes. The block cache
survives the reset, so the 199 blocks an edit did not touch are still hits.

### D24: scroll position is clamped only once the document is measured

Block heights are only known after rendering, so the total is unknown until the
whole document has been measured, and measurement is chunked so that jumping to
the end of a 100,000-line document costs several frames rather than one long
freeze. Until the total is known, scrolling is clamped to what *has* been
measured, the title bar shows no position, and the scrollbar is indeterminate —
rather than showing a guessed total that jumps when the guess is corrected.

### D25: benchmark results

Run on the development machine (Apple Silicon, macOS) with
`cargo bench --bench render`. These are recorded, not asserted; see Section 15.6.

| Benchmark | Result |
|---|---|
| `parse_document/1000_lines` | 113 µs |
| `parse_document/10000_lines` | 1.10 ms |
| `parse_document/100000_lines` | 11.3 ms |
| `first_frame/1000_lines` | 1.23 ms |
| `first_frame/10000_lines` | 1.26 ms |
| `first_frame/100000_lines` | 1.26 ms |
| `scroll_large_document/warm_cache` | 7.8 µs per frame |
| `scroll_large_document/cold_cache` | 1.22 ms |

The first-frame figure is flat from 1,000 to 100,000 lines, which is the
windowed renderer doing what it is for: opening a document costs what the
visible screen costs and nothing more. A scrolled frame against a warm cache is
7.8 µs against the 16.6 ms that 60 fps allows.

These are not the Linux numbers. Section 14's targets are re-measured on Linux
in D89.

## M3 — Vault walking and the files sidebar

### D26: the walk finds everything; the tree decides what to show

`files.include_hidden` and `files.show_all` are applied when the visible rows
are flattened, not when the vault is walked. Toggling either with `.` or `a` is
then a re-flatten rather than a re-read of the filesystem, which is what makes
both instant on a large vault.

`files.respect_gitignore` is the exception: honouring `.gitignore` is a property
of the walk itself, so changing it needs a new walk. Nothing in the UI offers
to; it is set once, by configuration or by `--no-gitignore`.

### D27: the walk is single-threaded

`ignore` can walk in parallel. It is not used here. The tree sorts what it
receives regardless of arrival order, and the streaming in batches already
hides the walk behind the first frame, so parallelism would buy wall clock on
exactly the vaults where it is least visible — at the cost of a second channel
and a harder cancellation story. Revisit if a vault is ever measured where the
tree is still filling in seconds after start-up.

### D27a: the walk is ordered by path

Found by CI: `tests/render.rs`'s search-results snapshot passed on the
development machine and failed on a GitHub runner, because `ignore` yields
entries in whatever order the filesystem returns them and the search reports
hits in walk order.

The tree sorts what it receives regardless, so this never showed there — but
search results that differ between two machines looking at the same vault are
results nobody can reproduce, quite apart from being unsnapshottable.
`sort_by_file_path` costs a sort per directory, which the walk is already
reading in full.

### D28: `require_git(false)`

A notes vault is frequently not a git repository, and `ignore` will not apply a
`.gitignore` outside one unless told to. `.gitignore` in a vault root means what
it says whether or not the directory has ever been committed.

### D29: batch size 256

One message per entry puts 10,000 wake-ups through the event loop for a vault
that size; one message for the whole walk leaves the tree empty until the walk
ends. 256 is small enough that the tree visibly fills in and large enough that
the channel is not the bottleneck.

### D30: the tree filter is a line in the sidebar, not an overlay

Section 8.3 lists the prompt overlay as serving new-file paths, rename, and the
project search query — not the tree filter. The filter is drawn as a line at the
top of the files mode, above the rows it is filtering, so what was typed and
what it matched are visible together. It shares the [`TextInput`] implementation
with the prompt overlay, and, like edit mode, it owns every key it can use while
it is open: a `q` typed into a filter must not quit perga.

### D31: a `[general]` and `[files]` table exist before the config loader does

M10 owns configuration loading. The walker and the tree need `[files]` now, so
the serde structures and their documented defaults were written with M3 and the
five-layer precedence chain that fills them in is still M10's. `[general]` came
with them for the one key M3 needs, `follow_symlinks`; `start_path`,
`allow_local_config`, `wrap`, and `tab_width` are declared with their documented
defaults but are not yet read by anything.

### D32: the ignored fixture is force-added to git

`tests/fixtures/vault/.gitignore` names `notes/`, and git applies a nested
`.gitignore` to this repository as well as to anything reading the fixture. The
one file the fixture needs there, `notes/ignored.md`, was therefore committed
with `git add -f`. A file added under that directory later needs the same.

### D33: the selection is a node, not a row

Rows are recomputed from scratch every frame and change under the selection
whenever a batch lands, a directory is expanded, or a filter is typed. Storing
the selected *node* rather than its row index means a walk finishing does not
move the user's cursor. When a toggle or a filter hides the selected node, the
selection falls back to the first visible row rather than vanishing.

## M4 — Link navigation and history

### D34: a leading `/` is tried against the vault root first

`[text](/docs/api.md)` is ambiguous: a vault written for a static site
generator means "from the vault root", and a document written against a
filesystem means the filesystem root. The vault root is tried first because
that is overwhelmingly what the target means inside a vault, and the filesystem
root is the fallback rather than the other way round. A target that exists in
neither place is broken, and nothing is created.

### D35: link positions are found in the rendered text, not derived from bytes

A link's rendered column cannot be computed from its byte offset: wrapping,
list markers, blockquote bars, and table borders all move text sideways, and
`tui-markdown` owns that layout. The offset↔line map gives the *line*, and the
column is found by searching that line's rendered text for the link's own
label. Several links with the same text on one line are handled by consuming
each match as it is used.

### D36: paths are normalised lexically, never canonicalised

`canonicalize` resolves symlinks and fails on a path that does not exist. A
broken link must resolve to `Broken`, not to an I/O error, and a vault whose
notes directory is a symlink must not have its links silently rewritten to
point somewhere the author never named. `..` is therefore collapsed lexically.

### D37: opening a document keeps the tab's history

`App::open` replaces the document, the layout, the scroll offsets, and the link
focus — everything about the *view*. The history and the read-or-edit mode
belong to the tab, not to the document in it, and survive. This is what makes
`Alt+←` work after following a link, and it is the reason `open` does not
simply assign a fresh `Tab`.

### D38: history is pushed by any navigation that replaces the document

Section 9.5 says following a link pushes the current location. Opening a
document from the tree does the same, because a reader who opened A and then B
expects Back to return to A, exactly as a browser does. `App::open` itself does
not push: it is the primitive both paths use, and the initial document has
nowhere to go back to.

### D39: hint labels are drawn over the document, not in a panel

A label only means anything on top of the link it belongs to. Hint mode is an
overlay in the focus sense — it owns input until it closes — but it is painted
into the viewport's own area. The focused-link highlight is suppressed while it
is open: two cues competing for the same links is worse than one.

### D40: a hint keystroke that matches nothing is dropped, not fatal

Typing a key with no matching label is a typo. It is discarded and hint mode
stays open, rather than cancelling the mode and leaving the reader to press `f`
again.

## M5 — Tabs

### D41: the tab bar window follows the active tab

Twenty labels do not fit on any terminal, so the bar draws a window and grows
it outwards from the active tab rather than from the first. The tab being read
is always on screen; an ellipsis at either end says there are more. Scrolling
the bar to find the tab you are already in is not something a reader should
have to do.

### D42: a label is elided in the middle

`2024-01-conference-notes.md` and `2024-01-conference-slides.md` are told apart
by their ends. A tail ellipsis makes every note in a dated vault look the same,
so the middle goes instead.

### D43: `Ctrl+Enter` on a non-document target does what `Enter` would

A background tab is only meaningful for a document. An anchor has nowhere else
to go, a directory is revealed in the tree, and an external URL belongs to the
desktop opener — so `Ctrl+Enter` falls through to the ordinary follow rather
than opening an empty tab or refusing.

### D44: `dirty` lives on the tab, not on the editor

The tab bar and the quit prompt both need to know whether a tab that is *not*
the active one has unsaved edits. Keeping the flag on `Tab` means neither has to
reach into an editor state that only exists while a tab is being edited. M9
sets it; M5 draws it.

## M6 — Outline mode and in-document find

### D45: the sidebar movement actions are shared by every mode

`tree_down` and `tree_expand_or_open` were M1 names for keys that turned out to
belong to the sidebar rather than to the tree. They are now `sidebar_down`,
`sidebar_up`, `sidebar_activate`, and `sidebar_back`, dispatched by whichever
mode is showing; the toggles and the filter kept their `tree_` names because
they really are the files mode's. Renamed rather than shadowed: two actions
bound to `j` in one context is exactly the conflict Section 12 warns about.

### D46: selection is per mode

Moving down the outline must not move the tree cursor underneath it, so the
outline keeps its own selection index and the tree keeps its own selected node.

### D47: the highlighted heading and the selected heading are different things

The outline highlights the heading the reader is *inside* — the last one whose
rendered line is at or above the top of the viewport, which is what "the
section I am reading" means when a section is taller than the screen — and it
separately marks the heading the reader has *selected* with the keyboard. One
moves with the scroll position, the other with `j` and `k`.

### D48: find counts in the source and highlights in the rendered text

A match needs a byte offset to be scrolled to, through the same offset↔line map
everything else uses, so matching runs over the document source. The
highlighting runs over the rendered text of the visible lines instead, because
the reader is looking at rendered text and a highlight landing on a different
run of characters is worse than none.

The two can disagree: a query containing Markdown punctuation — `](`, `**` —
counts in the source and highlights nowhere. The alternative is measuring the
whole document before the first search can report a count, which costs more
than the case is worth.

### D49: matching folds case per character, not per string

`str::to_lowercase` can change a string's length: `İ` folds to two characters.
Searching a folded copy and reusing its offsets against the original would put
a match in the wrong place in a Turkish document, so offsets are recovered by
folding character by character.

### D50: typing another character keeps the reader where they are

An incremental search that jumps back to the first match on every keystroke
fights the reader as they narrow a query. After a refresh the current match
becomes the nearest one at or after where they already were.

## M7 — Wiki-links and backlinks

### D51: wiki-links are scanned for, not parsed

`[[Page]]` is not Markdown, and `pulldown-cmark` sees it as a paragraph
containing brackets. Reconstructing the pairs from its event stream is less
reliable than reading the source, so extraction is two passes over the same
text: the parser for Markdown links, and a scanner for wiki-links. The first
pass also collects the ranges that hold code, raw HTML, and frontmatter, which
is what keeps a `[[Page]]` written inside a fenced block from becoming a link.

### D52: `![[Page]]` links rather than embeds

Some tools read the bang prefix as "transclude this page here". perga does not
embed, and a link to the page is the honest fallback — silently dropping the
syntax would lose the reference altogether.

### D53: the index knows files, and backlinks are computed from them

The cache stores what each file *contains*, not a pre-computed backlink map.
Backlinks are derived on demand by resolving every indexed link through the
same resolver the reader's `Enter` uses, so a forward link and a backlink can
never disagree. A vault where that becomes too slow to do per frame wants a
memoised reverse map; at 10,000 files it does not.

### D54: an exact-case filename match beats a case-insensitive one outright

Section 9.6 lists them as separate steps, which means a vault holding both
`Setup.md` and `setup.md` is not ambiguous when the link says which. Only when
no exact-case candidate exists does the case-insensitive set become the answer,
and then all of it does — including, correctly, an ambiguity between two files
that differ only in case.

### D55: following a wiki-link before the index is ready waits

Resolving against a half-built index would send the reader to an arbitrary
page — or report a page as missing that is about to be found — and look like a
bug in their own notes. Until the index is ready the status bar says
`Still indexing…`, and the links sidebar shows the progress behind that.

### D56: `Token Rotation.md` in the fixture vault

The resolution order in Section 9.6 has no step that turns a page name's spaces
into hyphens, so `[[Token Rotation]]` resolves to a file named `Token
Rotation.md` and not to `token-rotation.md`. The fixture was renamed to match
what the specification actually says rather than an extra normalisation step
being added to make the old name work.

### D57: the picker widget is shared

The disambiguation overlay and the quick switcher of Section 9.7 are the same
shape — a title, a list, one selected row — so they share `ui::overlay::switcher`
rather than growing two implementations that drift apart.

## M8 — Search

### D58: the search walks the vault itself

The searcher runs its own `ignore` walk rather than reading the tree the
sidebar holds. The tree is main-thread state and the search is not on the main
thread; sharing it would need a lock on every frame. Both walks use the same
`WalkOptions`, so search and tree agree about what is in the vault — including
the ignore rules — without either waiting on the other.

### D59: a new search cancels the old one by dropping its handle

`SearchHandle` cancels on drop, and starting a search replaces the handle. A
reader retyping a query does not accumulate threads: each one unwinds out of
`grep`'s own iteration at the next line it reads, which is what the thread-leak
test in `tests/search.rs` asserts.

### D60: fuzzy matching runs on the main thread

10,000 paths is a few hundred kilobytes and scores in well under a frame.
`nucleo`'s own worker pool would buy nothing at that size and would make the
switcher's results lag the keystrokes that produced them. The `Matcher` is kept
between keystrokes for its scratch buffers.

### D61: an empty switcher shows recents, not the vault

Section 8.3 asks for the recent list on an empty query. `Fuzzy::search`
therefore returns nothing for an empty query rather than "everything,
unordered" — the two are different answers and only one of them is useful.

### D62: the search state belongs to the window, not to a tab

Section 8.2 describes the search mode as showing "the last project-wide
search". One set of results the whole window shares, unlike find-in-document,
which is per tab because it is about the document in front of the reader.

### D63: `/pattern/` turns on regex for one search

A prompt wrapper rather than a mode: the configured `search.regex` decides the
default, and a reader who wants one regular expression writes it between
slashes without changing their configuration. An invalid pattern is reported in
the sidebar and the previous results stay put.

## M9 — Editor, file operations, and live reload

### D64: dirty is a content comparison, not a flag

The buffer hashes its lines and compares against the hash of what was last on
disk. Undoing back to the saved text therefore makes the tab clean again, which
an "edited" flag would not — and the reader who undid their way back to where
they started should not be asked whether to save nothing.

### D65: the mtime conflict check has a one-second tolerance

Some filesystems store whole seconds. Comparing exactly would make every save
on those report a conflict that is not there, and a conflict prompt the reader
learns to dismiss is worse than none.

### D66: the atomic write is a sibling, not a temporary directory

`rename` is only atomic within one filesystem, so the temporary file is written
beside its target. It is named `.<file>.perga-<pid>.tmp` — dotted, so an
interrupted save leaves nothing the tree shows by default — and removed on
every failure path.

### D67: `$EDITOR` handoff belongs to the event loop

`App` is deliberately terminal-free, and running an editor means leaving the
alternate screen and raw mode entirely and putting them back afterwards. `o`
therefore sets a path on `App` and the loop does the work, the same way `Ctrl+Z`
already suspends. The command is split on whitespace so
`external_command = "code --wait"` works; the *path* stays a separate argument
and never goes through a shell.

### D68: perga's own writes are claimed once

After a save the `(path, mtime)` pair is recorded. The watcher's report of that
exact write is dropped and the record consumed. Without it, every save races the
dirty flag it has just cleared: the write lands, the watcher reports it, and the
document reloads on top of the buffer that produced it.

A second change to the same path with a *different* mtime clears the record and
reloads: that is somebody else writing.

### D69: renaming does not rewrite links

Section 9.11 is explicit, and the reason is worth restating: rewriting links
across a vault is easy to get wrong and impossible to undo. perga renames the
file, follows every tab that had it open, moves it in the tree and the index,
and then *says* how many documents now link to the old name. The search mode
finds them.

### D70: a paste is one `insert_str`

Bracketed paste arrives as a single event and is inserted in one call, so
`tui-textarea` records it as one undo step. Feeding it character by character
would make undoing a 5,000-line paste 5,000 key presses.

### D71: recovery files are written on the way out, not continuously

A signal gives no chance to ask, so `ForceQuit` parks every dirty buffer under
`$XDG_STATE_HOME/perga/recovery/` before it exits, and entering edit mode on a
document that has one offers it back. Writing them continuously would double
every keystroke's cost for a case that happens once.

### D72: the `$EDITOR` handoff is not covered by an automated test

Driving a real `vim` needs a pseudo-terminal, which is a dependency and a class
of flakiness this project does not otherwise have. `hand_over` is small, and
every part of it that can be tested without one — resolving the command from
configuration and the environment, refusing when there is none, refusing while
the buffer is dirty — is. **Verified by hand** on this machine with
`EDITOR=vim`: the editor takes the screen, exits cleanly, and perga repaints
with the file reloaded. A reviewer on another platform should repeat it.

## M10 — Configuration, theming, session

### D73: layers are merged as TOML, and typed once at the end

Each layer is parsed into a `toml::Table` and merged key by key before anything
is deserialised. Typing each layer separately and then merging the typed values
would need every field to become an `Option` — the layer that did not mention a
key must not overwrite the one that did — and would double the schema.

### D74: an invalid value is isolated by retrying key by key

A table that will not deserialise is rebuilt one key at a time: each key is
tried on its own, the ones that work are kept, and the ones that do not produce
a warning naming them. That is what makes `sidebar_width = "wide"` cost one
setting rather than the whole `[ui]` table. It is quadratic in the number of
keys, which is fine at a dozen and only happens when something is already wrong.

`deny_unknown_fields` is kept on the schema structs, so the same loop catches
an unknown key and an invalid value and reports both with serde's own message.

### D75: a remap replaces an action's defaults rather than adding to them

`"quit" = "ctrl+q"` means `q` should stop quitting. A remap that only ever added
bindings would leave a user unable to free a key, which is most of what
remapping is for.

### D76: `[keys]` action names are derived, not listed

The name is the snake-cased variant — `toggle_sidebar`, `scroll_top` — computed
from the action rather than written in a second table beside it, so a new action
cannot be added without a name and the two cannot drift. `SetSidebarMode` is the
one action carrying a payload, and it is spelled `sidebar_mode_<mode>`.

### D77: the terminal background is detected from `COLORFGBG` only

Section 11.3 also asks for an OSC 11 query with a 50 ms timeout. It is **not
implemented**, and the reason is structural rather than an omission: reading the
reply means reading stdin, and stdin belongs to the input thread that Section
7.1 requires for the 0% idle CPU target. Querying before that thread starts
would delay the first frame, which 11.3 forbids; querying after it means racing
the thread for the reply and hoping `crossterm` does not swallow the escape
sequence as a key press.

So `theme.name = "auto"` reads `COLORFGBG`, which rxvt, Konsole, and several
others set, and uses `dark` otherwise — which is what 11.3 asks for when
detection fails. A user on a light terminal that sets no `COLORFGBG` writes
`theme.name = "light"` once. Revisit if `crossterm` grows a first-class
terminal-query API.

### D78: degrade before stripping

`NO_COLOR` wins over everything, and degrading a theme that has already had its
colours removed would have nothing to do. So the order is: resolve, degrade to
ANSI-256 when `COLORTERM` does not claim truecolour, then strip if `NO_COLOR` is
set.

### D79: `high-contrast` sets every colour its base sets

A theme file inherits what it does not mention, and `dark` is the base. A key
left out of `high-contrast` would quietly pull a truecolour value in from
`dark`, which defeats the whole point of the theme. The test in
`src/theme/builtin.rs` walks every resolved style and fails on anything outside
the sixteen ANSI colours — that is what caught `selection` and `code_inline`.

### D80: the shipped default config is a file, not a string literal

`docs/default-config.toml` is `include_str!`'d for `--generate-config` and
parsed by a test that asserts it produces exactly `Config::defaults()`. The
reference block, the flag's output, and the actual defaults are therefore one
thing, and cannot drift.

### D81: a session drops a tab whose file has gone

Restoring is best-effort by design. A tab pointing at a file that has since been
deleted or renamed is dropped rather than opened empty, and a session that ends
up with no tabs at all leaves the welcome screen alone.

## M11 — Documentation, packaging, release

### D82: `release.yml` is generated, and CI checks that it still is

`dist init` produced it from `dist-workspace.toml`, and it is committed
unmodified. A `dist generate --check` job in `ci.yml` fails if someone edits the
workflow by hand — the next `dist generate` would silently undo them, and a
release pipeline that quietly reverts is worse than one that fails loudly.

`aarch64` needed no configuration: `dist` reaches for `cargo-zigbuild` itself
when it sees a cross build.

### D83: the man page and the completions are generated by one script

`packaging/generate-assets.sh` runs the built binary. `dist` calls it through
`[[dist.extra-artifacts]]`, `cargo deb` and `cargo generate-rpm` read what it
writes, and a CI job runs it so a change to the CLI that breaks generation fails
here rather than in a distribution's build farm.

They are generated by the *binary* rather than a `build.rs` because sharing the
`clap` definition with a build script means duplicating or `#[path]`-including
the CLI module. They are generated for the host, not per target, because they
do not vary by target and a cross-built binary cannot be run to produce them.

### D83a: the generated assets are produced by a build-setup step

Found by the first release run, which failed in both build jobs with
`failed to copy asset from target/assets/perga.1`. `dist` collects the
`include` paths in the **local** build job, while `[[dist.extra-artifacts]]`
commands run in the separate **global** job — so the files did not exist yet
when the archive was assembled.

`ci.github.build-setup` names a YAML fragment of extra steps injected into the
build jobs, and `packaging/generate-assets.sh` runs there, in the same job that
assembles the archive. The `extra-artifacts` entry stays as well: that is what
attaches the four files to the release on their own, which packagers building
from the release rather than from the tarball ask for.

The fragment lives at `.github/build-setup.yml` and not in
`.github/workflows/`, where `dist` resolves the path from: a file of bare steps
is not a valid workflow, and GitHub flags every one it finds in that directory.

### D83b: a closed pipe is a clean exit

Found by exercising the released tarball: `perga note.md | head` printed
`writing to stdout: Broken pipe` and exited 1. Section 9.12 exists for
`perga README.md | less -R`, and pressing `q` in `less` produces exactly that.
Print mode now treats `BrokenPipe` as the end of the job — no message, exit
zero — which is what every other tool that writes to a pipe does.

### D83c: the installer puts the binary in `~/.local/bin`

`dist` defaults to `CARGO_HOME`. That is right for a tool whose users all have
a Rust toolchain, and wrong here: perga ships a static binary and its audience
is terminal users. `~/.local/bin` is on `PATH` out of the box on current
distributions, where `~/.cargo/bin` is only on `PATH` for someone who has
already installed Rust — and telling everyone else to `source ~/.cargo/env`
before they can read a Markdown file is a poor first impression.

`dist`'s installer has no way to install a man page or completions, so the
one-liner is binary-only. That is what the tarball and the distribution
packages are for, and `README.md` says so beside the command.

### D83d: the status bar hints at `Tab` first

Found by the first person to run the released binary: they could not work out
how to reach the file tree. The status bar advertised `Ctrl+B sidebar`, which
*hides* it — so the one key labelled "sidebar" made the sidebar disappear, and
nothing anywhere mentioned `Tab`.

`Tab focus the file tree` is now the first hint in the status bar and on the
welcome screen, and the toggle is labelled `hide sidebar`. First in the list
matters: hints are dropped from the right as the terminal narrows, so the one
a new reader needs most is the last to go.

### D83e: the `Edit` context inherits nothing

Reported by the first person to use edit mode, who asked the obvious question:
you have bound single letters like `q` and `m` — what happens when I type them
into a document?

They quit perga, opened the help overlay, and vanished, respectively. Keymap
lookup fell back to `Global` from every context including `Edit`, while the
module's own documentation said the text area owns every key the `Edit`
context does not claim. The code contradicted its stated intent, and Section
12 names this exact collision.

`Edit` now inherits nothing. `Ctrl+S`, `Esc`, `Ctrl+Z`, and `Ctrl+Y` are the
whole of it; everything else is text. That also costs edit mode the `Global`
bindings — `Ctrl+O`, `Ctrl+T`, `Ctrl+B` and the rest — which is the intended
trade: `Ctrl+W` deleting a word matters more inside a buffer than closing a
tab, and `Ctrl+C` is handled before the keymap, so there is always a way out.

### D83f: every theme colour is held to WCAG AA, by a test

Reported from real use: "I had trouble reading the text in the dark theme."
Measured, and they were right — thirteen keys of the default theme sat at
3.36:1 or below, three of them with `dim` on top of that. Body text was fine
at 12:1; it was everything *around* the document that could not be read: the
sidebar's mode row, the path in the title bar, inactive tab labels, search
result line numbers, unchecked task items, and every "nothing here" line.

Section 11.2 asked for 4.5:1 only of the `light` theme's body text. That was
too narrow a rule, and the gap it left is exactly what shipped.

Both truecolour themes now clear **4.5:1 for anything carrying text and 3:1
for a border or a rule** — the WCAG AA thresholds for text and for a
user-interface component. Two tests enforce it and name the offending key:
one against each style's own surface, one against the selection background,
because a selected row keeps its own foreground. The second caught four keys
the first did not, all sitting between 4.06 and 4.45.

`dim` is gone from the muted colours. On most terminals it halves the
intensity, which undoes the contrast the colour was picked for.

`high-contrast` is not measured: its colours are the sixteen ANSI names, whose
values are whatever the reader has configured, and perga cannot know them.
That is also why it exists.

### D83g: degradation searches the whole palette, and is measured

The contrast fix in D83f measured the themes as written. It should have
measured what terminals actually receive: `COLORTERM` is unset on plenty of
them — including the one the report came from — and those get the ANSI-256
approximation.

Two problems, found by extending the test to the degraded palette.

**The approximation was crude.** It decided "is this grey?" with a per-channel
threshold and then snapped each channel to the colour cube. `#313244`, the dark
theme's selection background, spans 19 across its channels, failed the grey
test, and landed on `(95, 95, 95)` — twice as light as intended, which ate the
contrast of every foreground drawn on it. The grey ramp had an entry 1 away.
The page background `#1e1e2e` became pure black, 63 units off.

It now searches all 240 palette entries by squared distance. Page background:
63 units off, now 14. Selection: 70, now 16. 240 comparisons per colour, once
when a theme loads.

**Two colours still failed after that**, and were adjusted: `code_inline` in
both themes, and the dark theme's muted grey, which read 5.81:1 as written and
4.41:1 once snapped.

The lesson is the one D83f already half-learnt: measure the thing that reaches
the reader, not the thing in the file.

### D83h: `m t` switches theme, and the session field finally means something

Section 9.10 asks the session to record "the last active theme if overridden at
runtime". Nothing could override it at runtime: the field was written on every
exit and read by nobody. Half a feature, and the half that was missing is the
one a reader touches.

`m t` cycles the three built-ins and then the theme directory, alphabetically —
a directory's read order is not stable and a cycle has to be. Three decisions
worth recording:

**`auto` is not a stop.** It is a way of *choosing* a theme at startup; as a
destination it would be a stop whose meaning depends on the terminal.

**The switch moves `theme.name`, not just the resolved theme.** The file
watcher re-reads `theme.name`, so leaving it behind would mean editing the
theme on screen reloads the previous one over the top. There is a test.

**`--theme` beats the session.** A flag on the command line is a decision about
*this* run. The session is only allowed to restore a theme when no flag pinned
one.

### D83i: a thematic break is a line, and a code block is a block

Asked whether documents could render more visually. Two things turned out to
be defects rather than matters of taste.

**`---` was printed as three characters.** `tui-markdown` passes a thematic
break through as the text that was typed. The theme has had a `markdown.rule`
key since the first version, `docs/theming.md` documents it, and nothing used
it. A rule is now a line of `─` across the width, in that style.

**A code block's background stopped where its text did.** A `Line`'s style only
paints the cells its spans occupy, so a short line left the background ending
mid-row and the block read as ragged text on a slightly darker strip. Each line
is now padded to the viewport width with the block's background.

A line *wider* than the viewport is deliberately left alone: clipping and the
`…` marker are the viewport's job, and padding it would defeat both. There is a
test for each half.

Neither shows up in a text snapshot, because the snapshot helper trims trailing
spaces — which is why both survived to a released version. The unit tests
assert the styles.

### D83j: a block quote is drawn with a bar

The third theme key that existed, was documented, and was used by nothing —
after `rule` and alongside it. `tui-markdown` passes a quote's `>` through as
the character that was typed, and `blockquote_bar` was named for a bar that
was never drawn.

The bar is put back **after** wrapping, not before. A quote is drawn with a bar
rather than a prefix precisely so the mark runs down the whole quote; marking
only the first rendered line would be the prefix again, badly. Nesting adds a
bar per level, and the content is wrapped into what is left.

Inline markup was checked at the same time and was already right: `**bold**`,
`*italic*`, `~~struck~~`, `` `code` `` and links all render styled with their
markers hidden. What still shows is `#` on headings — which the specification's
own layout sketch in Section 8.1 draws that way, so it stays until someone asks
otherwise.

### D83k: `#` on a heading is configurable, and defaults to on

Asked how it would look without them. With colour it is cleaner: a heading is
already coloured and bold, so the `#` is redundant. Without colour it is not —
`strip_colors` keeps modifiers, and every heading level in every built-in theme
is *only* bold, so h1 through h6 collapse into each other and into an inline
`**bold**` phrase. The `#` count is then the sole carrier of level.

So `ui.show_heading_markers`, default `true`. Nobody loses anything, and a
reader on a colour terminal can turn it off. The specification's own layout
sketch in Section 8.1 draws `# Authentication`, which is the other reason the
default stays.

Edit mode is unaffected either way: it shows the source in a text area, so the
`#` is always there when you are writing.

### D83l: print mode reads the configuration

Found while checking the key above: setting it changed nothing under `--print`.
`print_mode` built its own `Theme::dark()` and never called `Config::load`, so
`--theme`, `theme.name`, `general.wrap`, and every `[ui]` key that affects
rendering were silently ignored by print mode — against Section 9.12, which
says the theme applies there.

It now loads the same five layers, with the document's own directory as the
vault root, because that is where a `.perga.toml` beside it would be.
Configuration warnings go to **stderr**: stdout is the document, and a reader
redirecting it into a file does not want a warning in the middle of it.

### D84: the archives are `.tar.xz`, and the release names have no version

That is what `dist` produces — `perga-x86_64-unknown-linux-musl.tar.xz`, inside
a directory of the same name, with the version in the tag rather than the
filename. The README, the PKGBUILD, and `docs/publishing.md` follow what the
tool actually emits rather than what the specification's prose sketched.

### D85: the social preview is a real frame, typeset

`tests/preview.rs` captures a 120x22 frame through the same renderer the
application uses and writes it to `demo/social-preview-frame.txt`; two
ImageMagick commands typeset it and overlay the wordmark. The layout, the tree,
and the document in the image are genuinely perga's output.

It is monochrome, because the capture is plain text — a photographic screenshot
of a real terminal would carry the theme's colours and is a fine replacement.
Both the frame and the commands are committed so the image can be regenerated
without guessing at the geometry.

### D86: what could not be verified here

Recorded honestly, per the environment caveat in Section 17.

**Verified on this machine, by driving the real binary through a pseudo-terminal:**

- The application starts on the fixture vault, draws the tree, walks into a
  directory with `l`, opens a document through the quick switcher, renders it,
  shows the help overlay generated from the keymap, and quits on `q`.
- Teardown is clean on every path tried: the alternate screen is left, the
  cursor comes back, and mouse tracking and bracketed paste are turned off. The
  same holds after `--debug-panic`, where the panic message is readable on the
  restored terminal and the exit status is a panic's.

**Also verified:**

- `dist init` ran, `dist plan` lists exactly the artefacts Section 16.3 asks
  for, and `dist generate --check` passes.
- `dist build --artifacts=local` was run against `x86_64-unknown-linux-gnu`
  (the host) with the target list temporarily changed, and the resulting
  tarball was extracted and exercised: `perga --version`, `perga --print`,
  `man -l perga.1`, and `bash -n` over the bash completions all work.
- `cargo publish --dry-run` succeeds.
- The man page and all three completion files generate and are non-empty.
- The `$EDITOR` handoff, by hand with `vim` (see D72).

**Not verified here, and why:**

- **The musl builds.** `rustc`'s musl standard library is not installed on this
  machine and installing it needs root. `dist build` for
  `x86_64-unknown-linux-musl` fails with `can't find crate for 'core'`, which
  is the missing target and not a problem with the configuration. The release
  workflow installs it.
- **The `aarch64` cross-build**, for the same reason, plus `cargo-zigbuild`.
- **The release workflow itself.** Running it needs a pushed tag and GitHub
  Actions.
- **`cargo deny check`.** Recorded in D87.
- **The demo GIF.** `vhs` is not installed here and it needs `ttyd` and
  `ffmpeg`. `demo/demo.tape` is written, committed, and documented, and
  `README.md` embeds `demo/demo.gif` — which does not exist yet. **The owner
  must run `cd demo && vhs demo.tape` once and commit the result**, or the
  image at the top of the README will be broken.
- **A fresh container installing from the release tarball.** No container
  runtime here. The local extract-and-run above is the closest equivalent that
  was possible; the `ldd` check in `docs/publishing.md` is the one to run on a
  real musl artefact.
- **The social preview upload.** GitHub does not read the file from the
  repository; it has to be uploaded under Settings → Social preview by hand.
  Noted in `demo/README.md`.

### D87b: v0.1.0 and v0.1.1 are released

Both tagged, built, and published. `v0.1.1` carries the closed-pipe fix and the
installer path change; its artefacts were downloaded and checked here —
checksums verify, the x86_64 binary is `static-pie linked`, it runs, and the
one-line installer now lands the binary somewhere already on `PATH`.

`packaging/PKGBUILD` carries `v0.1.1`'s real checksums. It has not been
submitted to the AUR: that needs an AUR account and is the owner's to do.

`cargo publish` has still not been run — see D87c.

### D87c: crates.io publication is the owner's call

`cargo publish --dry-run` passes on every push. The real thing was not run: it
cannot be undone, it claims the `perga` name permanently, and nothing about
finishing the milestones requires it. `docs/publishing.md` has it as step 8.

### D87: `cargo deny check` passes, and the allow list was narrowed to fit

`advisories ok, bans ok, licenses ok, sources ok` on the committed dependency
tree. `cargo-deny` is installed in CI with `taiki-e/install-action`, and the
same command runs on every push.

`BSD-2-Clause` was removed from the licence allow list: it warned as
`license-not-encountered`, and Section 16.6 says an allow list should cover the
permissive set *actually present* rather than a wider one kept "just in case".
Adding a dependency that needs it back is a deliberate act with a line in this
file, which is the point.

### D88: the dependency licences actually present

For packagers, and so that a future addition is visibly a change:

| Licence | Why it is allowed |
|---|---|
| `MIT`, `Apache-2.0` | perga's own pair, and most of the tree |
| `Apache-2.0 WITH LLVM-exception` | `wasi` and the `linux-raw-sys` family |
| `BSD-3-Clause` | `encoding_rs`, reached through `grep-searcher` |
| `ISC` | `inotify` and `inotify-sys`, through `notify` |
| `Unicode-3.0` | `unicode-ident` |
| `Zlib` | `foldhash` and `miniz_oxide` |
| `MPL-2.0` | `nucleo` and `option-ext`. File-level copyleft: permitted for a linked library, and not used for perga's own code |
| `CC0-1.0` | `notify`, a public-domain dedication strictly more permissive than the rest |

Several crates offer a licence that is *not* on the list alongside one that is
— `ryu` is `Apache-2.0 OR BSL-1.0 OR MIT`, and the BurntSushi crates
(`ignore`, `memchr`, `grep-*`) are `Unlicense OR MIT`. `cargo deny` takes the
allowed half, which is why `BSL-1.0` and `Unlicense` are absent from the list
and the check still passes.

Regenerate the report with `cargo deny check licenses`.

### D89: every performance target in Section 14, measured on Linux

`cargo bench --bench render --bench vault` and
`cargo test --release --test timings -- --ignored`, on the development machine
(Linux, x86_64). These are recorded, not asserted; see Section 15.6.

| Target (Section 14) | Target | Measured |
|---|---|---|
| Cold start to first frame, 1,000-file vault | < 50 ms | **1.6 ms** |
| Cold start to first frame, 10,000-file vault | < 100 ms | **0.7 ms** |
| Full backlink index, 10,000 files | < 3 s, off-thread | **112 ms** |
| Open a 5 MB document | < 100 ms to first frame | **69 ms** (4.8 MB) |
| Scroll a 100,000-line document | sustained 60 fps (16.6 ms) | **0.6 ms** per frame |
| First search results, 10,000 files | < 200 ms | **47 ms** for the *whole* search |
| Idle CPU | 0% | 0% by construction — one blocking `recv` |
| Resident memory, 10,000-file vault | < 150 MB | not measured; see below |

The criterion benchmarks behind them:

| Benchmark | Result |
|---|---|
| `parse_document/1000_lines` | 473 µs |
| `parse_document/10000_lines` | 4.73 ms |
| `parse_document/100000_lines` | 49.2 ms |
| `first_frame/1000_lines` | 2.68 ms |
| `first_frame/10000_lines` | 2.79 ms |
| `first_frame/100000_lines` | 2.89 ms |
| `scroll_large_document/warm_cache` | 15.7 µs |
| `scroll_large_document/cold_cache` | 2.85 ms |
| `walk_vault/1000_files` | 2.44 ms |
| `walk_vault/10000_files` | 20.9 ms |
| `first_frame/tree_1000_files` | 506 µs |
| `first_frame/tree_10000_files` | 4.83 ms |
| `first_frame/rows_1000_files` | 169 ns |
| `first_frame/rows_10000_files` | 179 ns |

Three of these are worth reading rather than skimming.

**First frame is flat from 1,000 to 100,000 lines** — 2.68 ms to 2.89 ms. That
is the windowed renderer doing what it is for: opening a document costs what
the visible screen costs and nothing more.

**Flattening the tree's visible rows is 179 ns at 10,000 files**, and does not
grow with the vault, because with everything collapsed only the top level is
walked. That is why `rows()` can be a pure function called every frame rather
than a cache that has to be invalidated.

**The whole search of a 10,000-file vault is 47 ms**, against a 200 ms target
for the *first* results. The streaming path shows its first hits well inside
that; the number above is the pessimistic one, measured through the
synchronous path the tests use.

**Resident memory is not measured.** Doing it honestly needs a real run against
a real vault with `/proc/self/status` sampled at a known point, and the
allocation profile is dominated by the block cache, which is bounded by what
has been *rendered* rather than by the vault's size. Worth measuring before
1.0; not something a criterion benchmark answers.