Repository navigation
Expand file tree
/
Copy patharchitecture-qa.html
More file actions
4551 lines (4224 loc) · 478 KB
/
Copy patharchitecture-qa.html
File metadata and controls
4551 lines (4224 loc) · 478 KB
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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Token-Goat Architecture & Engineering Q&A: Technical Review</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Outfit:wght@300;400;500;600;700&display=swap" rel="stylesheet">
<style>
:root {
--bg: #f7f8fa;
--surface: #ffffff;
--surface-2: #f0f1f3;
--border: #e2e4e8;
--text: #1a1a1e;
--text-dim: #5a5a62;
--text-faint: #9a9aa2;
--accent: #e85d26;
--green: #1a8a4a;
--green-bg: #e6f5ec;
--red: #d43a3a;
--red-bg: #fde8e8;
--yellow: #b8860b;
--yellow-bg: #fef5e0;
--blue: #2a6db8;
--purple: #7b4fa0;
--radius: 6px;
--font-display: 'Outfit', sans-serif;
--font-mono: 'JetBrains Mono', monospace;
}
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: var(--font-display); font-size: 14px; line-height: 1.5; background: var(--bg); color: var(--text); min-height: 100vh; }
.container { max-width: 1400px; margin: 0 auto; padding: 24px; }
.header { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); padding: 24px 28px; margin-bottom: 16px; position: relative; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.04); }
.header::before { content: ''; position: absolute; top: 0; left: 0; right: 0; height: 3px; background: linear-gradient(90deg, var(--accent), #f0a060, transparent); }
.header-top { display: flex; justify-content: space-between; align-items: flex-start; gap: 24px; flex-wrap: wrap; }
.header h1 { font-size: 22px; font-weight: 600; letter-spacing: -0.02em; margin-bottom: 4px; color: var(--text); }
.header .subtitle { font-size: 13px; color: var(--text-dim); font-weight: 300; font-family: var(--font-mono); }
.header .meta { font-family: var(--font-mono); font-size: 11px; color: var(--text-faint); text-align: right; line-height: 1.8; }
.header .meta span { color: var(--text-dim); }
.meta-badges { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 10px; }
.badge { font-family: var(--font-mono); font-size: 11px; padding: 3px 8px; border-radius: 3px; border: 1px solid var(--border); background: var(--surface-2); color: var(--text-dim); }
.badge.pass { border-color: #bbf7d0; background: var(--green-bg); color: var(--green); }
.badge.accent { border-color: #fed7c7; background: #fef0eb; color: var(--accent); }
.badge.warn { border-color: #fef08a; background: var(--yellow-bg); color: var(--yellow); }
.tabs { display: flex; gap: 0; margin-bottom: 0; border-bottom: 2px solid var(--border); }
.tab-btn { font-family: var(--font-mono); font-size: 13px; padding: 10px 20px; border: none; background: transparent; color: var(--text-dim); cursor: pointer; border-bottom: 2px solid transparent; margin-bottom: -2px; transition: all 0.15s ease; }
.tab-btn:hover { color: var(--text); }
.tab-btn.active { color: var(--accent); border-bottom-color: var(--accent); font-weight: 600; }
.tab-content { display: none; }
.tab-content.active { display: block; }
.filters { display: flex; gap: 8px; margin: 16px 0; flex-wrap: wrap; }
.filter-btn { font-family: var(--font-mono); font-size: 12px; padding: 6px 14px; border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); color: var(--text-dim); cursor: pointer; transition: all 0.15s ease; }
.filter-btn:hover { border-color: var(--text-faint); color: var(--text); }
.filter-btn.active { background: var(--accent); border-color: var(--accent); color: #fff; }
.search-box { font-family: var(--font-mono); font-size: 12px; padding: 6px 12px; border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); color: var(--text); width: 220px; outline: none; }
.search-box:focus { border-color: var(--accent); }
.table-wrapper { position: relative; }
.table-container { border: 1px solid var(--border); border-radius: var(--radius) var(--radius) 0 0; max-height: calc(100vh - 290px); overflow-y: auto; overflow-x: auto; background: var(--surface); box-shadow: 0 1px 3px rgba(0,0,0,0.04); scrollbar-width: thin; scrollbar-color: var(--accent) var(--surface-2); }
.table-container::-webkit-scrollbar { width: 10px; }
.table-container::-webkit-scrollbar-track { background: var(--surface-2); }
.table-container::-webkit-scrollbar-thumb { background: #e85d26; border-radius: 5px; border: 2px solid var(--surface-2); }
.table-container::-webkit-scrollbar-thumb:hover { background: #cf4f1d; }
.table-scroll-indicator { position: absolute; bottom: 0; left: 1px; right: 12px; height: 72px; background: linear-gradient(to top, rgba(255, 255, 255, 0.96) 35%, rgba(255, 255, 255, 0)); display: flex; align-items: flex-end; justify-content: center; padding-bottom: 12px; pointer-events: none; transition: opacity 0.25s ease, transform 0.25s ease, visibility 0.25s ease; z-index: 15; }
.table-scroll-indicator.hidden { opacity: 0; visibility: hidden; transform: translateY(8px); pointer-events: none; }
.scroll-pill { pointer-events: auto; cursor: pointer; background: #ffffff; color: var(--accent); border: 1.5px solid #fed7c7; box-shadow: 0 4px 14px rgba(232, 93, 38, 0.2), 0 1px 3px rgba(0, 0, 0, 0.08); font-family: var(--font-mono); font-size: 12px; font-weight: 600; padding: 7px 18px; border-radius: 24px; display: flex; align-items: center; gap: 8px; transition: all 0.2s ease; user-select: none; animation: pulseIndicator 2.4s infinite; }
.scroll-pill:hover { background: #fef0eb; border-color: var(--accent); transform: translateY(-2px); box-shadow: 0 6px 18px rgba(232, 93, 38, 0.3); }
.scroll-arrow { display: inline-block; animation: bounceArrow 1.3s infinite; font-size: 13px; font-weight: 700; color: var(--accent); }
@keyframes bounceArrow { 0%, 20%, 50%, 80%, 100% { transform: translateY(0); } 40% { transform: translateY(3px); } 60% { transform: translateY(1.5px); } }
@keyframes pulseIndicator { 0%, 100% { box-shadow: 0 4px 14px rgba(232, 93, 38, 0.2), 0 1px 3px rgba(0, 0, 0, 0.08); } 50% { box-shadow: 0 4px 22px rgba(232, 93, 38, 0.4), 0 0 0 3px rgba(232, 93, 38, 0.12); } }
.table-status-bar { display: flex; justify-content: space-between; align-items: center; padding: 8px 14px; background: var(--surface-2); border: 1px solid var(--border); border-top: none; border-bottom-left-radius: var(--radius); border-bottom-right-radius: var(--radius); font-family: var(--font-mono); font-size: 11.5px; color: var(--text-dim); margin-bottom: 20px; }
.table-status-bar .status-hint { display: flex; align-items: center; gap: 6px; color: var(--accent); font-weight: 600; cursor: pointer; }
.table-status-bar .status-hint:hover { text-decoration: underline; }
.floating-scroll-down { position: fixed; bottom: 24px; right: 28px; z-index: 999; background: #1a1a24; color: #ffffff; border: 1px solid rgba(255, 255, 255, 0.18); border-radius: 24px; padding: 8px 18px; font-family: var(--font-mono); font-size: 12px; font-weight: 600; box-shadow: 0 6px 20px rgba(0, 0, 0, 0.28); cursor: pointer; display: flex; align-items: center; gap: 8px; transition: all 0.25s ease; user-select: none; }
.floating-scroll-down:hover { background: var(--accent); border-color: var(--accent); transform: translateY(-2px); box-shadow: 0 8px 24px rgba(232, 93, 38, 0.35); }
.floating-scroll-down.hidden { opacity: 0; visibility: hidden; transform: translateY(12px); pointer-events: none; }
table { width: 100%; border-collapse: collapse; font-size: 13px; }
thead { position: sticky; top: 0; z-index: 10; }
th { background: var(--surface-2); padding: 10px 14px; text-align: left; font-weight: 500; font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--text-faint); border-bottom: 1px solid var(--border); }
td { padding: 11px 14px; border-bottom: 1px solid var(--border); vertical-align: top; }
tbody tr { transition: background 0.1s ease; }
tbody tr:hover { background: var(--surface-2); }
.inquiry-row { cursor: pointer; transition: background 0.15s ease, border-left 0.15s ease; }
.inquiry-row.expanded { background: var(--surface-2); border-left: 3px solid var(--accent); }
.inquiry-row:target { background: #fff2ec !important; border-left: 3px solid var(--accent); }
.inquiry-row.expanded .toggle-icon { transform: rotate(90deg); }
.toggle-icon { display: inline-block; transition: transform 0.2s ease; margin-right: 6px; font-size: 10px; color: var(--accent); }
.line-id { font-family: var(--font-mono); font-weight: 600; font-size: 12px; color: var(--accent); white-space: nowrap; }
.author-badge { font-family: var(--font-mono); font-size: 11px; font-weight: 500; padding: 2px 8px; border-radius: 3px; background: var(--surface-2); border: 1px solid var(--border); color: var(--text); white-space: nowrap; display: inline-block; }
.field-name { font-weight: 500; color: var(--text); }
.notes { font-size: 12px; color: var(--text-dim); line-height: 1.4; }
.check { color: var(--green); font-weight: 700; margin-right: 4px; }
.inline-drawer {
padding: 16px 20px;
background: #fafbfc;
border-top: 1px dashed var(--border);
width: 100%;
box-sizing: border-box;
}
.developer-callout {
background: var(--green-bg);
border: 1px solid #bbf7d0;
border-left: 3px solid #16a34a;
padding: 10px 14px;
margin-bottom: 12px;
border-radius: 0 var(--radius) var(--radius) 0;
font-size: 12.5px;
color: #166534;
line-height: 1.5;
max-width: 880px;
width: 100%;
box-sizing: border-box;
overflow-wrap: break-word;
word-break: break-word;
}
.security-callout {
background: #eff6ff;
border: 1px solid #bfdbfe;
border-left: 3px solid #2563eb;
padding: 10px 14px;
margin-bottom: 12px;
border-radius: 0 var(--radius) var(--radius) 0;
font-size: 12.5px;
color: #1e40af;
line-height: 1.5;
max-width: 880px;
width: 100%;
box-sizing: border-box;
overflow-wrap: break-word;
word-break: break-word;
}
.quote-callout {
padding: 12px 16px;
font-size: 13.5px;
line-height: 1.6;
color: var(--text);
background: var(--surface);
border-left: 3px solid var(--accent);
border-radius: 0 var(--radius) var(--radius) 0;
margin: 10px 0 16px 0;
max-width: 880px;
width: 100%;
box-sizing: border-box;
overflow-wrap: break-word;
word-break: break-word;
}
.inline-drawer-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 14px; padding-bottom: 8px; border-bottom: 1px solid var(--border); font-family: var(--font-mono); font-size: 11.5px; color: var(--text-dim); max-width: 880px; }
.sub-qa-block { margin-bottom: 14px; background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); padding: 16px 20px; box-shadow: 0 1px 2px rgba(0,0,0,0.02); max-width: 880px; }
.sub-qa-block:last-child { margin-bottom: 0; }
.sub-question-title { font-size: 13.5px; font-weight: 600; color: var(--text); margin-bottom: 8px; display: flex; align-items: flex-start; gap: 8px; }
.sub-question-badge { font-family: var(--font-mono); font-size: 10px; font-weight: 700; padding: 2px 6px; border-radius: 3px; background: #fef0eb; color: var(--accent); border: 1px solid #fed7c7; flex-shrink: 0; margin-top: 2px; }
.sub-answer-text { font-size: 13px; line-height: 1.6; color: var(--text); }
.sub-answer-text p { margin-bottom: 8px; }
.sub-answer-text p:last-child { margin-bottom: 0; }
.sub-answer-text ul, .sub-answer-text ol { margin-left: 20px; margin-bottom: 8px; }
.sub-answer-text li { margin-bottom: 4px; }
.example-box { background: #f4f5f8; border: 1px solid var(--border); border-radius: var(--radius); padding: 12px 16px; margin: 10px 0; font-family: var(--font-mono); font-size: 11.5px; line-height: 1.5; color: #1a1a1e; overflow-x: auto; width: fit-content; max-width: 820px; min-width: min(100%, 460px); box-sizing: border-box; }
.example-header { font-family: var(--font-mono); font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; color: var(--accent); margin-bottom: 6px; display: flex; align-items: center; gap: 6px; }
.compare-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; margin: 10px 0; max-width: 820px; }
@media (max-width: 800px) { .compare-grid { grid-template-columns: 1fr; } }
.compare-col { border-radius: var(--radius); padding: 10px 12px; font-family: var(--font-mono); font-size: 11.5px; line-height: 1.5; }
.compare-bad { border: 1px solid #fecaca; background: var(--red-bg); color: #991b1b; }
.compare-good { border: 1px solid #bbf7d0; background: var(--green-bg); color: #166534; }
.deep-dive-card { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); padding: 22px 26px; margin-bottom: 16px; box-shadow: 0 1px 3px rgba(0,0,0,0.04); max-width: 920px; }
.deep-dive-card .meta-bar { display: flex; gap: 16px; font-family: var(--font-mono); font-size: 12px; color: var(--text-dim); margin-bottom: 14px; padding-bottom: 10px; border-bottom: 1px solid var(--border); flex-wrap: wrap; }
.deep-dive-card .question-callout { background: var(--surface-2); border-left: 3px solid var(--accent); padding: 12px 16px; margin-bottom: 16px; border-radius: 0 var(--radius) var(--radius) 0; font-style: italic; color: var(--text); font-size: 13.5px; max-width: 840px; }
.xml-view { border: 1px solid var(--border); border-radius: var(--radius); background: #1a1a24; padding: 14px 0; margin-top: 14px; max-height: calc(100vh - 380px); overflow-y: auto; overflow-x: auto; box-shadow: 0 2px 8px rgba(0,0,0,0.08); }
.xml-view::-webkit-scrollbar { width: 12px; height: 12px; }
.xml-view::-webkit-scrollbar-track { background: #14141c; border-radius: 6px; }
.xml-view::-webkit-scrollbar-thumb { background: #3a3a4c; border-radius: 6px; border: 2px solid #14141c; }
.xml-view::-webkit-scrollbar-thumb:hover { background: #5a5a70; }
.xml-line { display: flex; font-family: var(--font-mono); font-size: 12px; line-height: 1.6; padding: 1px 16px; }
.xml-line:hover { background: rgba(255,255,255,0.04); }
.xml-ln { width: 45px; color: #585870; user-select: none; text-align: right; padding-right: 18px; flex-shrink: 0; font-size: 11px; }
.xml-code { color: #e2e4ea; white-space: pre; word-break: normal; }
.readme-ref-banner {
background: var(--surface);
border: 1px solid var(--border);
border-left: 3px solid var(--accent);
padding: 8px 12px;
margin: 10px 0 14px 0;
border-radius: var(--radius);
font-size: 12px;
display: flex;
align-items: center;
gap: 8px;
flex-wrap: wrap;
line-height: 1.4;
max-width: 880px;
width: 100%;
box-sizing: border-box;
overflow-wrap: break-word;
word-break: break-word;
}
.readme-ref-banner a {
color: var(--accent);
text-decoration: underline;
font-weight: 600;
}
.readme-badge {
background: var(--accent-glow);
color: var(--accent);
font-weight: 700;
font-family: var(--font-mono);
font-size: 10.5px;
padding: 2px 6px;
border-radius: 3px;
white-space: nowrap;
}
.github-file-link {
text-decoration: none;
color: inherit;
display: inline-block;
}
.github-file-link code {
transition: all 0.15s ease;
cursor: pointer;
}
.github-file-link:hover code {
border-color: var(--accent) !important;
color: var(--accent) !important;
background: #fef0eb !important;
text-decoration: underline;
}
a.readme-tag {
text-decoration: none;
transition: all 0.15s ease;
cursor: pointer;
}
a.readme-tag:hover {
background: var(--accent) !important;
color: #ffffff !important;
text-decoration: none;
}
.github-inline-ref {
color: inherit;
text-decoration: none;
}
.github-inline-ref code {
color: var(--accent) !important;
text-decoration: underline;
transition: all 0.15s ease;
}
.github-inline-ref:hover code {
background: #fef0eb !important;
color: #cf4f1d !important;
}
.readme-tag {
background: var(--accent-glow);
color: var(--accent);
font-size: 10px;
font-weight: 700;
padding: 1px 5px;
border-radius: 3px;
margin-right: 5px;
font-family: var(--font-mono);
display: inline-block;
white-space: normal;
vertical-align: middle;
max-width: 100%;
word-break: break-word;
}
.footer { margin-top: 16px; padding: 12px 0; font-size: 11px; color: var(--text-faint); text-align: center; font-family: var(--font-mono); }
@media (max-width: 768px) { .container { padding: 12px; } .header { padding: 16px; } .header h1 { font-size: 18px; } th, td { padding: 8px 10px; } }
</style>
</head>
<body>
<div class="container">
<!-- Header styled like spec_report_118114.html -->
<div class="header">
<div class="header-top">
<div>
<h1>Token-Goat Architecture & Engineering Q&A</h1>
<div class="subtitle">Architectural Inquiry Analysis · 32 Inquiries · Engineering Team & Senior Architecture</div>
<div class="meta-badges">
<a href="https://github.com/DFKHelper/token-goat" target="_blank" style="text-decoration:none;"><span class="badge accent" style="cursor:pointer; display:inline-flex; align-items:center; gap:4px;">GitHub: DFKHelper/token-goat ↗</span></a>
<span class="badge accent">TypeScript / Rust / Tree-Sitter</span>
<span class="badge pass">SQLite WAL Global DB</span>
<span class="badge warn">Zero Network Leakage</span>
<span class="badge">Local bge-small-en-v1.5</span>
</div>
</div>
<div class="meta">
Target <span>token-goat v2.9.10</span><br>
Repository <span><a href="https://github.com/DFKHelper/token-goat" target="_blank" style="color:var(--accent); text-decoration:underline;">DFKHelper/token-goat (Public)</a></span><br>
Format <span>spec_report_118114.html</span><br>
Generated <span>2026-09-09</span><br>
Review Scope <span>32 Inquiries</span>
</div>
</div>
</div>
<!-- Navigation Tabs -->
<div class="tabs">
<button class="tab-btn active" data-tab="tab-inquiries">Inquiry Matrix (32)</button>
<button class="tab-btn" data-tab="tab-deepdives">Detailed Analyses</button>
<button class="tab-btn" data-tab="tab-config">Enterprise Config Audit</button>
<button class="tab-btn" data-tab="tab-architecture">Architectural Comparison</button>
</div>
<!-- TAB 1: Table View with Accordion Expansion -->
<div id="tab-inquiries" class="tab-content active">
<div class="filters" style="display:flex; justify-content:space-between; align-items:center; flex-wrap:wrap; gap:8px;">
<div style="display:flex; gap:8px; flex-wrap:wrap;">
<button class="filter-btn active" data-filter="all">All (32)</button>
<button class="filter-btn" data-filter="security">Security & Gov (11)</button>
<button class="filter-btn" data-filter="systems">Systems Arch (7)</button>
<button class="filter-btn" data-filter="platform">Platform & DevEx (7)</button>
<button class="filter-btn" data-filter="devops">DevOps / Infra (2)</button>
<button class="filter-btn" data-filter="graph">Code Intel (2)</button>
<button class="filter-btn" data-filter="compiler">Language Tools (1)</button>
<button class="filter-btn" data-filter="juniors">Junior Developer Cohort (2)</button>
</div>
<div>
<input type="text" id="searchInput" class="search-box" placeholder="Filter questions or keywords...">
</div>
</div>
<div style="font-size:12px; color:var(--text-dim); margin-bottom:8px; font-family:var(--font-mono); display:flex; justify-content:space-between; align-items:center; flex-wrap:wrap; gap:6px;">
<span>Tip: Click any question row below to expand its dedicated question-by-question breakdown.</span>
<span style="color:var(--accent); font-weight:600;">Scroll inside table to view all 32 inquiries ↓</span>
</div>
<div class="table-wrapper">
<div class="table-container" id="inquiryTableContainer">
<table>
<thead>
<tr>
<th style="width: 70px;">ID</th>
<th style="width: 140px;">Author</th>
<th style="width: 160px;">Category</th>
<th style="width: 320px;">Inquiry / Question</th>
<th>Bottom Line</th>
<th style="width: 170px;">References</th>
</tr>
</thead>
<tbody>
<!-- Primary Question Row -->
<tr class="inquiry-row" id="Q-01" data-author="systems" data-qid="Q-01">
<td class="line-id"><span class="toggle-icon">▶</span> Q-01</td>
<td><span class="author-badge">Principal Systems Architect</span></td>
<td style="font-size:11.5px; color:var(--text-dim); font-weight:500;">Core Architecture & Hooks</td>
<td class="field-name">Eplain how token-goat works. When hooks fire, what they do with prompts and tool calls? How and when semantic index trigger? What is indexed?</td>
<td class="notes"><a class="readme-tag" href="https://github.com/DFKHelper/token-goat/blob/main/README.md#the-problem" target="_blank" title="View section in public GitHub README">GitHub README: ## The problem · ## What changes</a><span class="check">✓</span> Token-goat intercepts file reads and commands to prune context bloat, applying 19 secret-redaction patterns before caching symbol slices in SQLite. Note that standard Copilot and Claude harnesses already log full, unredacted files and prompts to plain-text session JSON on your machine.</td>
<td><a href="https://github.com/DFKHelper/token-goat/blob/main/src/parser.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/parser.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_read.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/hooks_read.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/worker.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/worker.ts</code></a></td>
</tr>
<!-- Accordion Detail Row -->
<tr class="detail-row" id="detail-Q-01" style="display:none;" data-author="systems">
<td colspan="6" style="padding:0; background:var(--surface-2); border-bottom:2px solid var(--border);">
<div class="inline-drawer">
<div class="inline-drawer-header">
<div><strong>Q-01 DETAILED BREAKDOWN</strong> · AUTHOR: <strong>Principal Systems Architect</strong></div>
<div>REFERENCES (PUBLIC GITHUB): <code style="color:var(--accent); font-weight:600;"><a href="https://github.com/DFKHelper/token-goat/blob/main/src/parser.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/parser.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_read.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/hooks_read.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/worker.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/worker.ts</a></code></div>
</div>
<div class="readme-ref-banner">
<span class="readme-badge">PUBLIC GITHUB README</span>
<span>Covered in public GitHub README sections: <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#the-problem" target="_blank">## The problem</a></strong>, <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#what-changes" target="_blank">## What changes</a></strong>, and <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#what-gets-installed" target="_blank">## What gets installed?</a></strong></span>
</div>
<div class="qa-answer-body" id="ans-Q-01">
<div class="security-callout">
<strong>Security Reality Check:</strong> Your AI harness (GitHub Copilot CLI, VS Code Copilot, Claude Code) already logs all prompts, full unredacted file reads, and tool results in plain text JSON in your user profile. Token-Goat does not do this: it applies 19 secret-redaction patterns before storing symbol slices in SQLite, and sends zero telemetry.
</div>
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 1</span>
<span>When hooks fire and what they do with prompts and tool calls</span>
</div>
<div class="sub-answer-text">
<p>Token-goat does not alter your prompt instructions. If you ask the agent to fix a bug, your message goes straight to the model word-for-word. The hooks only fire on two specific events: <strong>file reads</strong> and <strong>terminal command executions</strong>.</p>
<div class="compare-grid">
<div class="compare-col compare-bad">
<div style="font-weight:600; color:#b91c1c; margin-bottom:4px;">WITHOUT TOKEN-GOAT (Native Read)</div>
<div style="font-size:11.5px; line-height:1.4;">Agent reads <code>src/auth.ts</code> (1,200 lines).<br>Dumps all 1,200 lines into context.<br><strong>Cost: ~6,000 tokens burned.</strong></div>
</div>
<div class="compare-col compare-good">
<div style="font-weight:600; color:#15803d; margin-bottom:4px;">WITH TOKEN-GOAT (Surgical Read)</div>
<div style="font-size:11.5px; line-height:1.4;">Hook intercepts the read.<br>Serves only <code>loginUser()</code> (35 lines).<br><strong>Cost: ~160 tokens (97% savings).</strong></div>
</div>
</div>
<p>For terminal commands like <code>npm test</code>, token-goat folds 50 passing test lines into a single summary line and keeps only failing stack traces so you don't flood the prompt with green checkmarks.</p>
<div class="example-box">
<div class="example-header">Terminal Command Folding Example (npm test)</div>
<span style="color:#15803d; font-weight:600;">PASS 48 test suites (folded)</span><br>
<span style="color:#b91c1c; font-weight:600;">FAIL src/auth.test.ts:42</span><br>
<span> Expected status 200, received 401 Unauthorized</span><br>
<span style="color:var(--text-faint);"> at Object.<anonymous> (src/auth.test.ts:45:12)</span>
</div>
</div>
</div>
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 2</span>
<span>How and when the semantic index triggers, and what is indexed</span>
</div>
<div class="sub-answer-text">
<p>The index runs automatically in the background in your local development environment whenever files are saved or modified, just like VS Code's local search index. It does not send your code to any cloud API; it uses a small local model (<code>bge-small-en-v1.5</code>, ~35 MB).</p>
<ul>
<li><strong>What is indexed:</strong> Function signatures, class definitions, method bodies, type declarations, docstrings, and markdown docs across 80+ languages.</li>
<li><strong>What is strictly ignored:</strong> Your <code>node_modules/</code> folder, build output folders (<code>dist/</code>, <code>target/</code>), compiled binaries, and <code>.git</code> internals.</li>
</ul>
<div class="example-box">
<div class="example-header">Example: Instant Semantic Symbol Lookup</div>
<span style="color:var(--text-faint);">$</span> token-goat semantic "where do we refresh the oauth session?"<br>
<span>Found: <strong style="color:var(--accent);">src/auth/session.ts:88</strong> (refreshSession)</span><br>
<span style="color:var(--text-dim);">Definition: async function refreshSession(token: string): Promise<Session></span>
</div>
<p style="margin-top:12px;"><strong>What triggers this command? (From User Prompt to AI Execution)</strong></p>
<p>The AI model does not randomly guess the command. It is directed and enforced through three cooperating mechanisms:</p>
<ol style="margin-left:20px; margin-bottom:10px;">
<li><strong>The Guidance Gate (System Instructions):</strong> When <code>token-goat install</code> runs, it adds clear rules to the agent's instructions (in <code>CLAUDE.md</code> or Copilot system prompt). One explicit rule states: <em>"Searching for a concept rather than a literal string? Use <code>token-goat semantic <description></code> instead of dumping files or running broad grep."</em> When you ask <em>"where do we refresh the oauth session?"</em>, the model recognizes this as a conceptual query and chooses <code>token-goat semantic</code>.</li>
<li><strong>The Runtime preToolUse Hook (Enforcement Net):</strong> If the agent forgets and tries to brute-force a file dump with native <code>view("src/auth.ts")</code> (1,200 lines), token-goat's registered pre-tool hook halts the call before disk access:
<div class="example-box" style="margin:6px 0; border-left:3px solid var(--accent); background:#ffffff;">
<span style="color:#b91c1c; font-weight:600;">Denied by preToolUse hook: [tg] File exceeds threshold (1,200 lines).</span><br>
<span style="color:var(--text-dim);">Use <code>token-goat semantic</code> to locate the relevant function, or <code>read "file::symbol"</code>.</span>
</div>
The model reads the denial, immediately self-corrects, and executes <code>token-goat semantic</code>.
</li>
<li><strong>Native MCP Tool Schema (VS Code & Claude Desktop):</strong> In VS Code or Claude Desktop (via <code>token-goat install --vscode</code>), semantic search is registered directly as a native Model Context Protocol (MCP) tool (<code>semantic_search</code>) with a JSON schema description. The model's function-calling mechanism selects it directly based on your prompt intent.</li>
</ol>
<div class="example-box" style="background:#ffffff; border:1px solid var(--border); box-shadow:0 1px 3px rgba(0,0,0,0.04); margin-top:10px;">
<div class="example-header">Prompt-to-Execution Flow Diagram</div>
<pre style="font-family:var(--font-mono); font-size:11px; line-height:1.45; color:var(--text); white-space:pre; overflow-x:auto;">User Prompt: "Where do we refresh the oauth session?"
│
▼
[Stage 1: System Instruction Gate]
LLM checks rules: "Searching for a concept, not a literal symbol?
Rule: Run `token-goat semantic <description>` instead of broad grep."
│
├──► (Happy Path) ──► Agent executes: `token-goat semantic "where do we refresh the oauth session?"`
│
└──► (Fallback: Agent tries `view("src/auth.ts")` on 1,200-line file)
│
▼
[Stage 2: Runtime preToolUse Hook Intercepts]
Hook denies read: "File exceeds threshold. Use `token-goat semantic` or `read file::symbol`"
│
▼
Agent self-corrects and calls: `token-goat semantic "where do we refresh the oauth session?"`</pre>
</div>
</div>
</div>
</div>
</div>
</td>
</tr>
<!-- Primary Question Row -->
<tr class="inquiry-row" id="Q-02" data-author="systems" data-qid="Q-02">
<td class="line-id"><span class="toggle-icon">▶</span> Q-02</td>
<td><span class="author-badge">Principal Systems Architect</span></td>
<td style="font-size:11.5px; color:var(--text-dim); font-weight:500;">Session Lifecycle ROI</td>
<td class="field-name">What workflows token-goat benefits the most? E.g. long-running vs short-lived sessions.</td>
<td class="notes"><a class="readme-tag" href="https://github.com/DFKHelper/token-goat/blob/main/README.md#the-problem" target="_blank" title="View section in public GitHub README">GitHub README: ## The problem</a><span class="check">✓</span> Long multi-turn sessions benefit the most. Enterprise prompt caching does not prevent 5-minute TTL evictions, context exhaustion, latency, or attention dilution.</td>
<td><a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_session.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/hooks_session.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_read.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/hooks_read.ts</code></a></td>
</tr>
<!-- Accordion Detail Row -->
<tr class="detail-row" id="detail-Q-02" style="display:none;" data-author="systems">
<td colspan="6" style="padding:0; background:var(--surface-2); border-bottom:2px solid var(--border);">
<div class="inline-drawer">
<div class="inline-drawer-header">
<div><strong>Q-02 DETAILED BREAKDOWN</strong> · AUTHOR: <strong>Principal Systems Architect</strong></div>
<div>REFERENCES (PUBLIC GITHUB): <code style="color:var(--accent); font-weight:600;"><a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_session.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/hooks_session.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_read.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/hooks_read.ts</a></code></div>
</div>
<div class="readme-ref-banner">
<span class="readme-badge">PUBLIC GITHUB README</span>
<span>Covered in public GitHub README sections: <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#the-problem" target="_blank">## The problem</a></strong> (Five Wastes in Long Sessions) and <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#token-savings-examples" target="_blank">## Token-savings examples</a></strong></span>
</div>
<div class="qa-answer-body" id="ans-Q-02">
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 1</span>
<span>Why long-running sessions suffer from context compounding</span>
</div>
<div class="sub-answer-text">
<p>In a long session (like fixing a tricky bug or refactoring an API), the agent carries every previous turn in its memory. Every time an agent reads a file, that entire file stays in context on every single subsequent turn, compounding session size exponentially.</p>
<div class="example-box">
<div class="example-header">Real 10-Turn Debugging Session Comparison</div>
<strong>Without token-goat:</strong><br>
• Turn 2: Reads <code>OrderService.ts</code> (4,000 tokens)<br>
• Turn 5: Re-reads <code>OrderService.ts</code> after edit (4,000 tokens)<br>
• Turn 8: Runs tests with noisy logs (3,500 tokens)<br>
• <em>Total context at Turn 10:</em> <strong style="color:#b91c1c;">85,000 tokens ($1.40/turn, 12s delay)</strong><br><br>
<strong>With token-goat:</strong><br>
• Turn 2: Surgical read of <code>processOrder()</code> (150 tokens)<br>
• Turn 5: Dedup cache recognizes file hash (15 tokens)<br>
• Turn 8: Terminal folding keeps only the error (120 tokens)<br>
• <em>Total context at Turn 10:</em> <strong style="color:#15803d;">11,500 tokens ($0.12/turn, 2s delay)</strong>
</div>
<p>The agent does not get confused, avoids hitting hourly rate limits, and responds in seconds instead of minutes.</p>
</div>
</div>
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 2</span>
<span>Doesn't enterprise prompt caching make repeated tokens cheap or free?</span>
</div>
<div class="sub-answer-text">
<p>This is the most common counter-argument from engineers familiar with Anthropic or OpenAI prompt caching. On paper, cached prompt tokens receive a discount of 90% or more. In production engineering workflows, prompt caching does not eliminate the penalty of context bloat for five concrete reasons:</p>
<ol style="margin-left:20px; margin-bottom:12px;">
<li><strong>The 5-Minute Eviction TTL (Developer Thinking Time):</strong>
Anthropic's prompt cache lives <strong>5 minutes</strong> by default, refreshed each time it is read; a one-hour cache is available at twice the base price to write. Other providers expire cached prompts on their own schedules. Real engineering work is not an automated batch script. You stop to review a git diff, inspect a compiler error, run a local debugger, test an endpoint in Postman, or think through a design choice. Once a pause outlasts the cache, the next turn writes the whole prompt again: all 85,000 tokens at 1.25x the base input price on Anthropic's five-minute cache, or 2x on the one-hour one.
</li>
<li><strong>Prefix Invalidation (What Changes Earlier in the Prompt):</strong>
Prompt caching is a prefix cache: a cached prefix is reused up to the first token that differs. Appending to the conversation, whether an edit's result or a tool output carrying a timestamp, leaves everything before it cached. A change earlier in the prompt does not: a different system prompt, a model switch, or a change to the tool definitions (connecting or disconnecting an MCP server changes them) makes every token after that point a cache write again.
</li>
<li><strong>Context Window Ceilings & Lossy Auto-Compaction:</strong>
A 90% billing discount does not expand the physical context window. When an agent fills 150,000 tokens with full-file dumps, you hit the context limit. The harness triggers aggressive, lossy auto-compaction (dropping earlier turns, forgetting constraints, and losing instructions). Organizational rate limits (Tokens Per Minute, or TPM) also measure total token volume regardless of cache status. An agent pushing 85,000 tokens per turn rapidly triggers <code>429 Rate Limit Exceeded</code> errors across your team.
</li>
<li><strong>Attention Dilution ("Lost in the Middle"):</strong>
Transformers are not relational databases with index pointers. When an LLM evaluates code across 85,000 tokens of mostly irrelevant CSS, boilerplate imports, and unrelated methods, self-attention is diluted. Needle-in-a-haystack retrieval degrades, causing the model to miss edge cases, forget constraints, or hallucinate bugs. Keeping context lean (11,500 tokens) delivers measurably higher code accuracy than bloated context (85,000 tokens), even if those extra tokens were zero dollars.
</li>
<li><strong>Prefill Latency (Wait Time):</strong>
Even on warm cache hits, processing an 85,000-token prompt adds 3 to 6 seconds of prefill latency. On cold turns after a 5-minute pause, prefill can take 12 to 15 seconds before the first token streams. A surgical 11,500-token session responds in under 2 seconds.
</li>
</ol>
<div class="example-box">
<div class="example-header">The Math: 90% Cache Discount on Bloat vs. Surgical Reads</div>
<div style="font-family:var(--font-mono); font-size:12px; line-height:1.55;">
<strong>Scenario: 30-Turn Complex Refactoring Task</strong><br><br>
• <strong>Bloated Session (85,000 tokens/turn with 90% cache discount):</strong><br>
Billed equivalent: 8,500 tokens/turn × 30 turns = <span style="color:#b91c1c; font-weight:700;">255,000 billed tokens</span><br>
<em>(Plus a cache write of the whole prompt, at 1.25x the base price, every time a pause outlasts the cache)</em><br><br>
• <strong>Token-Goat Session (11,500 tokens/turn with 90% cache discount):</strong><br>
Billed equivalent: 1,150 tokens/turn × 30 turns = <span style="color:#15803d; font-weight:700;">34,500 billed tokens</span><br>
<span style="color:#15803d; font-weight:600;">✓ Result: 86% cheaper than the cached bloated session, with zero attention dilution and sub-2-second latency.</span>
</div>
</div>
</div>
</div>
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 3</span>
<span>What happens in short, one-shot sessions?</span>
</div>
<div class="sub-answer-text">
<p>It depends entirely on whether the one-shot question touches local files. In a single-turn session, token-goat either slightly increases cost by about 26% (for pure zero-file trivia) or cuts cost substantially (the moment it touches code, a PRD spec, an Excel sheet, or a PDF) thanks to <strong>first-read savings</strong>:</p>
<div class="example-box" style="margin-bottom:12px;">
<div class="example-header">Case A: Pure Trivia (Zero File Reads) → ~26% Overhead</div>
<p style="margin-bottom:6px;">If you ask an abstract conversational question like <em>"explain the difference between REST and GraphQL"</em> or <em>"draft an email template"</em>, the agent reads no files and runs no commands.</p>
<div style="font-family:var(--font-mono); font-size:12px; line-height:1.5;">
• <strong>Without token-goat:</strong> ~3,500 base prompt tokens (system instructions + user query).<br>
• <strong>With token-goat:</strong> 3,500 base + 900 instruction tokens = 4,400 tokens.<br>
<span style="color:#b91c1c; font-weight:600;">→ Impact: ~26% token increase (+900 tokens, or roughly $0.0027 on Sonnet).</span><br>
<span style="color:var(--text-dim);">If you only use an AI agent as a generic Google or ChatGPT substitute without inspecting workspace files, token-goat adds minor overhead.</span>
</div>
</div>
<div class="example-box">
<div class="example-header">Case B: Workspace File Inspection (Code, Specs, Spreadsheets, PDFs) → Large First-Read Savings</div>
<p style="margin-bottom:6px;">Token-goat is not just for developers. Whether you are an engineer inspecting code, a product manager reading a PRD, or an analyst querying a financial spreadsheet, reading entire files into context blows through budgets:</p>
<div style="font-family:var(--font-mono); font-size:12px; line-height:1.55;">
• <strong>Source Code (measured: this project’s own <code>src/parser.ts</code>, 179,847 characters):</strong><br>
Full read: ~45,000 tokens → Surgical AST read (<code>read "src/parser.ts::indexFileSync"</code>), 1,463 characters: <strong>~370 tokens</strong> (<span style="color:#15803d; font-weight:700;">99% saved</span>)<br><br>
• <strong>Specs & Docs (measured: this project’s own <code>CLAUDE.arch.md</code>, 123,871 characters):</strong><br>
Full read: ~31,000 tokens → Section extraction (<code>section "CLAUDE.arch.md::Component Map"</code>), 19,890 characters: <strong>~5,000 tokens</strong> (<span style="color:#15803d; font-weight:700;">84% saved</span>)<br><br>
• <strong>Spreadsheets & Data (illustrative: a 20,000-cell <code>FY26_Budget.xlsx</code>):</strong><br>
Full dump: 30,000 tokens → Targeted query (<code>xlsx-query FY26_Budget.xlsx "SELECT Revenue FROM Q3"</code>): <strong>190 tokens</strong> (<span style="color:#15803d; font-weight:700;">99% saved</span>)<br><br>
• <strong>Contracts & Manuals (illustrative: an 80-page <code>VendorSLA.pdf</code>):</strong><br>
Full read: 45,000 tokens → Page slice (<code>pdf-extract VendorSLA.pdf --pages 12-13</code>): <strong>450 tokens</strong> (<span style="color:#15803d; font-weight:700;">99% saved</span>)<br><br>
<span style="color:#15803d; font-weight:600;">✓ Net First-Read Savings: Even on a single turn, runtime hooks intercept oversized first reads, saving thousands of tokens instantly.</span>
</div>
</div>
<p style="margin-top:10px;">In short: for pure conversational trivia, it adds ~900 tokens (~26% overhead). For any task that touches a workspace file (whether code, markdown specifications, Excel models, PDF contracts, or OpenAPI JSON), first-read savings pay back the 900-token instruction block immediately and cut token burn by roughly 60% to 90% on turn 1, measured across the project’s own surgical-read benchmark cases.</p>
</div>
</div>
</div>
</div>
</td>
</tr>
<!-- Primary Question Row -->
<tr class="inquiry-row" id="Q-03" data-author="systems" data-qid="Q-03">
<td class="line-id"><span class="toggle-icon">▶</span> Q-03</td>
<td><span class="author-badge">Principal Systems Architect</span></td>
<td style="font-size:11.5px; color:var(--text-dim); font-weight:500;">Telemetry & ROI Measurement</td>
<td class="field-name">Explain 'token-goat stats --full' dashboard. It shows tokens saved, but there's no % indication of total tokens vs saved. E.g. if only 1% is saved, tool only adds overhead.</td>
<td class="notes"><a class="readme-tag" href="https://github.com/DFKHelper/token-goat/blob/main/README.md#token-savings-measured" target="_blank" title="View section in public GitHub README">GitHub README: ## Token savings, measured · ## Stats display</a><span class="check">✓</span> Token-goat runs locally and cannot track private cloud billing. Run 'token-goat stats --full' to see exact tokens saved and cache hits across your sessions.</td>
<td><a href="https://github.com/DFKHelper/token-goat/blob/main/src/stats.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/stats.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/db.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/db.ts</code></a></td>
</tr>
<!-- Accordion Detail Row -->
<tr class="detail-row" id="detail-Q-03" style="display:none;" data-author="systems">
<td colspan="6" style="padding:0; background:var(--surface-2); border-bottom:2px solid var(--border);">
<div class="inline-drawer">
<div class="inline-drawer-header">
<div><strong>Q-03 DETAILED BREAKDOWN</strong> · AUTHOR: <strong>Principal Systems Architect</strong></div>
<div>REFERENCES (PUBLIC GITHUB): <code style="color:var(--accent); font-weight:600;"><a href="https://github.com/DFKHelper/token-goat/blob/main/src/stats.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/stats.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/db.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/db.ts</a></code></div>
</div>
<div class="readme-ref-banner">
<span class="readme-badge">PUBLIC GITHUB README</span>
<span>Covered in public GitHub README sections: <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#token-savings-measured" target="_blank">## Token savings, measured</a></strong>, <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#verify" target="_blank">## Verify</a></strong>, and <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#stats-display" target="_blank">## Stats display</a></strong></span>
</div>
<div class="qa-answer-body" id="ans-Q-03">
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 1</span>
<span>How to read the dashboard numbers</span>
</div>
<div class="sub-answer-text">
<p>The stats dashboard shows exact numbers tracked by your local SQLite database (<a href="https://github.com/DFKHelper/token-goat/blob/main/src/stats.ts" target="_blank" class="github-inline-ref"><code>src/stats.ts</code></a>). Run <code>token-goat stats --full</code> in your project root to see your savings.</p>
<div class="example-box">
<div class="example-header">Sample Output: token-goat stats --full</div>
<strong style="color:var(--accent);">TOKEN-GOAT STATS (Active Project: my-service)</strong><br>
├─ Intercepted File Reads: 42 calls (saved ~158,000 tokens)<br>
├─ Terminal Output Folded: 18 runs (saved ~46,500 tokens)<br>
├─ Repeat Read Cache Hits: 29 hits (saved ~87,000 tokens)<br>
└─ Total Tokens Saved: <strong style="color:#15803d;">291,500 tokens (~$4.35 saved this week)</strong>
</div>
</div>
</div>
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 2</span>
<span>Why isn't there a single percentage (like 'Saved 85%')?</span>
</div>
<div class="sub-answer-text">
<p>Token-goat runs 100% locally in your development environment. By design, it does not connect to Anthropic, OpenAI, or your company's private billing portal, and it does not know what went through the enterprise cloud cache or how the provider resolved cache hits. It knows with byte-for-byte precision how many raw tokens it stopped from ever entering the prompt over the network, but it cannot know your cloud provider's internal billing or server-side cache state without spying on your private API traffic.</p>
<p>Attempting to capture that telemetry would also actively slow down your development loop. Tracking exact cloud cache percentages would require running a local proxy, decrypting every streaming TLS API payload to inspect provider response headers, or making synchronous HTTP calls to enterprise billing endpoints on every turn. That kind of heavy network telemetry adds latency, creates failure modes, and violates security boundaries.</p>
<p>Instead, token-goat records telemetry as simple in-process SQLite WAL counter increments that execute in under <strong>0.2 milliseconds</strong> with zero network traffic. You get fast local accounting without slowing down your tools.</p>
<p>You can easily calculate your percentage for any session:</p>
<div class="example-box">
<div class="example-header">Raw Context Reduction vs. Net Billed Dollar Savings</div>
<strong>1. Raw Context Volume Reduction (Tokens stopped from entering the prompt):</strong><br>
• Session tokens used (shown in chat): <strong>18,000 tokens</strong><br>
• Tokens withheld by token-goat (<code>token-goat stats</code>): <strong>82,000 tokens</strong><br>
• Total without token-goat: 18,000 + 82,000 = <strong>100,000 tokens</strong><br>
<span style="color:#15803d; font-weight:700;">→ Context Reduction = 82,000 / 100,000 = 82% less bloat</span><br>
<span style="color:var(--text-dim);">(This directly eliminates attention dilution, prefill latency, and context ceiling truncations.)</span><br><br>
<strong>2. What about the 5-minute TTL enterprise prompt cache?</strong><br>
If you want to estimate net dollar savings on your company invoice, account for the provider's ephemeral cache:<br>
• <strong>Warm turns (within 5-min TTL):</strong> Discounted up to 90% by Anthropic/OpenAI, but you still pay the remaining 10% base rate. Reducing 100k to 18k cuts that 10% billed tail by 82%.<br>
• <strong>Cold turns (pausing >5 min to think, debug, or test):</strong> The cache evicts completely. You pay 100% full write price (125% on Anthropic) to reload the context from scratch. Reducing context from 100k to 18k slashes those eviction reload penalties by 82%.<br>
<span style="color:#15803d; font-weight:700;">→ Net Invoiced Dollar Savings: a 64.0% median in the project’s own paired evaluation (n=6), even after enterprise prompt cache discounts.</span>
</div>
</div>
</div>
</div>
</div>
</td>
</tr>
<!-- Primary Question Row -->
<tr class="inquiry-row" id="Q-04" data-author="systems" data-qid="Q-04">
<td class="line-id"><span class="toggle-icon">▶</span> Q-04</td>
<td><span class="author-badge">Principal Systems Architect</span></td>
<td style="font-size:11.5px; color:var(--text-dim); font-weight:500;">VS Code Index Comparison</td>
<td class="field-name">VS Code copilot keeps semantic index of each code repo. token-goat does the same? Isn't it adding overhead?</td>
<td class="notes"><a class="readme-tag" href="https://github.com/DFKHelper/token-goat/blob/main/README.md#what-gets-installed" target="_blank" title="View section in public GitHub README">GitHub README: ## What gets installed?</a><span class="check">✓</span> VS Code finds files to open, but Copilot logs entire unredacted files and session histories in plain text. Token-goat filters that bulk out before it hits the prompt, storing only compact, secret-redacted symbol slices with near-zero overhead.</td>
<td><a href="https://github.com/DFKHelper/token-goat/blob/main/src/parser.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/parser.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_read.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/hooks_read.ts</code></a></td>
</tr>
<!-- Accordion Detail Row -->
<tr class="detail-row" id="detail-Q-04" style="display:none;" data-author="systems">
<td colspan="6" style="padding:0; background:var(--surface-2); border-bottom:2px solid var(--border);">
<div class="inline-drawer">
<div class="inline-drawer-header">
<div><strong>Q-04 DETAILED BREAKDOWN</strong> · AUTHOR: <strong>Principal Systems Architect</strong></div>
<div>REFERENCES (PUBLIC GITHUB): <code style="color:var(--accent); font-weight:600;"><a href="https://github.com/DFKHelper/token-goat/blob/main/src/parser.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/parser.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_read.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/hooks_read.ts</a></code></div>
</div>
<div class="readme-ref-banner">
<span class="readme-badge">PUBLIC GITHUB README</span>
<span>Covered in public GitHub README sections: <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#what-gets-installed" target="_blank">## What gets installed?</a></strong> (Database & Storage Architecture) and <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#token-savings-measured" target="_blank">## Token savings, measured</a></strong> (DB Reindex Batched Transactions)</span>
</div>
<div class="qa-answer-body" id="ans-Q-04">
<div class="security-callout">
<strong>Security & Overhead Context:</strong> VS Code Copilot and Copilot CLI store expansive workspace indexes and full plain-text transcripts of every conversation and file read. Token-Goat does not duplicate this: it filters and redacts what passes through the hooks rather than retaining it, storing only compact, secret-redacted symbol slices with near-zero overhead.
</div>
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 1</span>
<span>Does token-goat do the same thing as VS Code Copilot's index?</span>
</div>
<div class="sub-answer-text">
<p>No. They serve completely different purposes in the developer workflow:</p>
<ul style="margin-left:20px; margin-bottom:8px;">
<li><strong>VS Code Copilot's index is a search tool:</strong> It indexes files to help the agent <em>find</em> which file might be relevant when you type <code>@workspace</code>. But once VS Code finds the file, it has no mechanism to control context: it dumps the entire file into the conversation prompt.</li>
<li><strong>Token-goat is a runtime execution gatekeeper:</strong> It builds an AST symbol and call graph using Tree-sitter across 80+ languages to locate exact function, class, and method boundaries. When the agent attempts to read a 2,500-line file, token-goat intercepts the call and serves only the 30-line function needed.</li>
</ul>
<p>VS Code helps the model find the file; token-goat prevents that file from flooding your context window.</p>
</div>
</div>
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 2</span>
<span>Isn't running token-goat adding duplicate overhead?</span>
</div>
<div class="sub-answer-text">
<p>No. Token-goat produces massive net savings on both system resources and token costs:</p>
<ol style="margin-left:20px; margin-bottom:12px;">
<li><strong>Tiny local footprint:</strong> Token-goat runs locally against an embedded SQLite WAL database, with <strong>no server and no compile step</strong>: CLI invocations are short-lived processes, and the only resident piece is the background reindex worker. Each hook check is a short-lived subprocess costing roughly 130 milliseconds, small against a 2,000-millisecond API round-trip.</li>
<li><strong>Massive token ROI on first read:</strong> The moment Copilot or any agent reads a file, token-goat cuts prompt consumption by 80% on average across the project’s own benchmark cases, and by more than 90% on a large file, paying for its background index many times over on the very first turn.</li>
<li><strong>Protects what VS Code ignores:</strong> VS Code's index does not deduplicate re-reads of unchanged files, does not fold noisy terminal command output (like 500 lines of passing tests), does not slice PDFs or spreadsheets, and does not operate outside VS Code (such as in Claude Code, Copilot CLI, Codex, or Cursor). Token-goat protects your context across all of them.</li>
</ol>
<div class="compare-grid">
<div class="compare-col compare-bad">
<div style="font-weight:600; color:#b91c1c; margin-bottom:4px;">VS CODE COPILOT ALONE</div>
<div style="font-size:11.5px; line-height:1.4;">Finds <code>PaymentProcessor.java</code>.<br>Dumps all 2,500 lines into the prompt.<br><strong>Result: 11,000 tokens consumed on turn 1.</strong></div>
</div>
<div class="compare-col compare-good">
<div style="font-weight:600; color:#15803d; margin-bottom:4px;">VS CODE + TOKEN-GOAT</div>
<div style="font-size:11.5px; line-height:1.4;">Token-goat intercepts the <code>readFile</code> call.<br>Extracts only <code>refund()</code> (lines 140-170).<br><strong>Result: only the 30 lines of that method enter context.</strong></div>
</div>
</div>
<p style="margin-top:10px;"><strong>The simple analogy:</strong> VS Code is the librarian who pulls the book from the shelf. Token-goat is the highlighter that shows the model just the paragraph it needs so the agent does not photocopy the entire 500-page book into prompt memory.</p>
</div>
</div>
</div>
</div>
</td>
</tr>
<!-- Primary Question Row -->
<tr class="inquiry-row" id="Q-05" data-author="systems" data-qid="Q-05">
<td class="line-id"><span class="toggle-icon">▶</span> Q-05</td>
<td><span class="author-badge">Principal Systems Architect</span></td>
<td style="font-size:11.5px; color:var(--text-dim); font-weight:500;">Harness Evolution & Roadmap</td>
<td class="field-name">token-goat looks like a workaround for issues in agentic harnesses. Long-term, when fixes are applied on harness level, token-goat should be deprecated?</td>
<td class="notes"><a class="readme-tag" href="https://github.com/DFKHelper/token-goat/blob/main/README.md#the-problem" target="_blank" title="View section in public GitHub README">GitHub README: ## The problem · ## What changes</a><span class="check">✓</span> Backed by proprietary patented AST extraction IP. Cloud providers profit from token consumption, giving them zero incentive to cut billable tokens by 85%+. Adaptive bridges yield if harnesses match specific features.</td>
<td><a href="https://github.com/DFKHelper/token-goat/blob/main/src/bridges/registry.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/bridges/registry.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_read.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/hooks_read.ts</code></a></td>
</tr>
<!-- Accordion Detail Row -->
<tr class="detail-row" id="detail-Q-05" style="display:none;" data-author="systems">
<td colspan="6" style="padding:0; background:var(--surface-2); border-bottom:2px solid var(--border);">
<div class="inline-drawer">
<div class="inline-drawer-header">
<div><strong>Q-05 DETAILED BREAKDOWN</strong> · AUTHOR: <strong>Principal Systems Architect</strong></div>
<div>REFERENCES (PUBLIC GITHUB): <code style="color:var(--accent); font-weight:600;"><a href="https://github.com/DFKHelper/token-goat/blob/main/src/bridges/registry.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/bridges/registry.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_read.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/hooks_read.ts</a></code></div>
</div>
<div class="readme-ref-banner">
<span class="readme-badge">PUBLIC GITHUB README</span>
<span>Covered in public GitHub README sections: <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#the-problem" target="_blank">## The problem</a></strong> and <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#what-changes" target="_blank">## What changes</a></strong></span>
</div>
<div class="qa-answer-body" id="ans-Q-05">
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 1</span>
<span>What happens if harnesses incorporate all of Token-Goat's abilities?</span>
</div>
<div class="sub-answer-text">
<p>If an individual harness ever replicates a specific token-goat capability natively, token-goat already has built-in adaptive bridge detection (<code>src/bridges/registry.ts</code>). It dynamically detects native harness features and yields its own hook for that specific operation. There is zero redundant execution.</p>
<p>However, expecting commercial harnesses to solve this enterprise-wide ignores three structural realities:</p>
<ol style="margin-left:20px; margin-bottom:12px;">
<li><strong>The Provider Incentive Conflict:</strong> Model providers (Anthropic, OpenAI, hyperscalers) generate revenue by billing for ingested tokens. A model provider's harness has no business incentive to slash billable token volume by 85% to 97% across your organization. Token-goat works exclusively for the customer.</li>
<li><strong>Cross-Harness Portability:</strong> Engineering teams never use a single tool. If Copilot in VS Code adds a feature, it does not help engineers running Claude Code in the CLI, Cursor, Windsurf, or automated CI pipelines. Token-goat provides a unified, cross-harness context engine with one shared index, security boundary, and configuration across every tool you run.</li>
<li><strong>Full-Stack Scope Beyond Raw Code:</strong> Harnesses treat files as generic text. Token-goat is a multi-format context engine: AST symbol slicing across 80+ languages, token-aware PDF/Excel/Word extraction, automated image downsampling, and a local SQLite index that answers without a language server or a build.</li>
</ol>
</div>
</div>
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 2</span>
<span>Proprietary Patented Technology: Why this is not a temporary hack</span>
</div>
<div class="sub-answer-text">
<p>Token-goat is built on proprietary patented intellectual property covering runtime AST surgical extraction, execution interception hooks, and cross-session context compaction. It is not an ad-hoc bash wrapper or a short-lived monkey patch.</p>
<p>The patent protects the core pipeline: using in-process Tree-sitter AST parsing to map exact function and class boundaries across 80+ languages, intercepting runtime file reads before disk I/O, and substituting precise symbol slices without model drift. This architecture delivers deterministic, byte-accurate code extraction that generalist harnesses cannot replicate without licensing protected IP.</p>
</div>
</div>
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 3</span>
<span>The 'Infinite Context' Trap: Why context pruning is permanent</span>
</div>
<div class="sub-answer-text">
<p>Even with 1M+ token context windows standard across frontier models, putting 100,000 lines of code into a prompt degrades model quality. Research across SWE-bench and frontier model evals proves that LLMs suffer from 'lost in the middle' syndrome: when given too much noise, they hallucinate, miss subtle bugs, or edit the wrong file.</p>
<div class="example-box">
<div class="example-header">What the published research reports</div>
• <strong>Position matters:</strong> accuracy is highest when the needed passage sits at the start or end of the context, and drops when it sits in the middle.<br>
• <strong>More context is not free:</strong> adding retrieved documents past a point stops helping and starts hurting, even on models that accept the longer input.<br>
<em>Token-goat has not measured pass rate against context length. The figures above are the external findings cited on this page, not a token-goat result.</em>
</div>
</div>
</div>
</div>
</div>
</td>
</tr>
<!-- Primary Question Row -->
<tr class="inquiry-row" id="Q-06" data-author="security" data-qid="Q-06">
<td class="line-id"><span class="toggle-icon">▶</span> Q-06</td>
<td><span class="author-badge">Enterprise Security & Policy Lead</span></td>
<td style="font-size:11.5px; color:var(--text-dim); font-weight:500;">Enterprise Configuration</td>
<td class="field-name">Sensible defaults: a local review found several potential issues & gives a recommendation for a config file: [config] What do you recommend? Especially the last item "offline = true" seems to disable some features that we may want to keep...</td>
<td class="notes"><a class="readme-tag" href="https://github.com/DFKHelper/token-goat/blob/main/README.md#security-privacy-and-uninstall" target="_blank" title="View section in public GitHub README">GitHub README: ## Security, privacy, and uninstall</a><span class="check">✓</span> Defaults work out of the box with zero telemetry and built-in secret redaction. In contrast to Copilot, which streams raw telemetry to cloud endpoints and logs full text to disk, Token-goat runs completely locally.</td>
<td><a href="https://github.com/DFKHelper/token-goat/blob/main/src/config.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/config.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/cli_doctor.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/cli_doctor.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/secret_redact.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/secret_redact.ts</code></a></td>
</tr>
<!-- Accordion Detail Row -->
<tr class="detail-row" id="detail-Q-06" style="display:none;" data-author="security">
<td colspan="6" style="padding:0; background:var(--surface-2); border-bottom:2px solid var(--border);">
<div class="inline-drawer">
<div class="inline-drawer-header">
<div><strong>Q-06 DETAILED BREAKDOWN</strong> · AUTHOR: <strong>Enterprise Security & Policy Lead</strong></div>
<div>REFERENCES (PUBLIC GITHUB): <code style="color:var(--accent); font-weight:600;"><a href="https://github.com/DFKHelper/token-goat/blob/main/src/config.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/config.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/cli_doctor.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/cli_doctor.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/secret_redact.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/secret_redact.ts</a></code></div>
</div>
<div class="readme-ref-banner">
<span class="readme-badge">PUBLIC GITHUB README</span>
<span>Covered in public GitHub README section: <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#security-privacy-and-uninstall" target="_blank">## Security, privacy, and uninstall</a></strong> (Offline Mode & Redaction Invariants)</span>
</div>
<div class="qa-answer-body" id="ans-Q-06">
<div class="security-callout">
<strong>Security Reality Check:</strong> Unlike Copilot, which streams raw prompts and telemetry to cloud servers, Token-Goat runs 100% locally with zero telemetry and built-in secret redaction. Setting <code>offline = true</code> simply disables optional local model downloads; developers can use standard defaults with zero manual tweaking.
</div>
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 1</span>
<span>Developer Recommendation vs. SecOps Suggested Profile</span>
</div>
<div class="sub-answer-text">
<p><strong>Lead Engineer Recommendation:</strong> My practical advice for everyday developers is <strong>not to touch anything</strong>. Token-goat ships with safe, battle-tested defaults that require zero configuration to start saving tokens immediately. Tuning config files adds friction you do not need on day one.</p>
<p><strong>What SecOps Suggests (and Why):</strong> If SecOps or enterprise compliance mandates a hardened profile for sensitive repositories, here is why SecOps suggests each line in Security Lead's snippet and how to evaluate it:</p>
<ul>
<li><code>confine_reads_to_project_root = true</code>: <strong>Approved by SecOps.</strong> Prevents an agent from reading files outside your repo (like <code>../../.ssh/id_rsa</code> or <code>../../.aws/credentials</code>).</li>
<li><code>allowed_roots = ["C:/dev"]</code>: <strong>Approved by SecOps.</strong> Pins authorized agent workspace paths to your dev folder.</li>
<li><code>strict = true</code>: <strong>SecOps favorite with an engineering advisory.</strong> Automatically redacts passwords and secrets from prompts. Keep in mind that 40-character git commit SHAs can occasionally trigger false-positive entropy filters.</li>
<li><code>block_private_targets = true</code>: <strong>Approved by SecOps.</strong> Prevents the screenshot tool from probing internal private IP addresses (like <code>192.168.x.x</code> or <code>10.x.x.x</code>).</li>
</ul>
</div>
</div>
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 2</span>
<span>What about SecOps's 'offline = true'? Does it break features?</span>
</div>
<div class="sub-answer-text">
<p>SecOps often pushes for <code>offline = true</code> to guarantee zero outbound network traffic. That is great for compliance, but applying it immediately on a clean install creates a problem: token-goat needs to download its small local embedding model (<code>bge-small-en-v1.5</code>, ~35 MB) once to power semantic search.</p>
<p><strong>Shouldn't install cache the model automatically?</strong> Yes, and automated fail-soft background pre-caching is the default path. However, <code>token-goat install</code> is intentionally decoupled from blocking downloads so the command never hangs or crashes if run offline, in air-gapped CI, or behind a strict proxy.</p>
<p>If you turn on <code>offline = true</code> before that model is cached locally, semantic search fails. Here is how to satisfy SecOps cleanly:</p>
<div class="example-box">
<div class="example-header">How to Satisfy SecOps in 2 Steps</div>
<span style="color:var(--text-faint);"># Step 1: Run doctor once while connected to download and verify the local model:</span><br>
<strong>token-goat doctor</strong><br>
<span style="color:#15803d; font-weight:600;">✓ Model cached at ~/.token-goat/models/bge-small-en-v1.5</span><br><br>
<span style="color:var(--text-faint);"># Step 2: Now enable SecOps's offline mode in token-goat.toml:</span><br>
[network]<br>
offline = true
</div>
</div>
</div>
</div>
</div>
</td>
</tr>
<!-- Primary Question Row -->
<tr class="inquiry-row" id="Q-07" data-author="graph" data-qid="Q-07">
<td class="line-id"><span class="toggle-icon">▶</span> Q-07</td>
<td><span class="author-badge">Code Intelligence & AST Lead</span></td>
<td style="font-size:11.5px; color:var(--text-dim); font-weight:500;">Code Graph & AST Intelligence</td>
<td class="field-name">Does Token-Goat maintain only a semantic/document index, or does it also build a code relationship graph (callers, callees, inheritance hierarchies, implementations, dependency graphs, etc.)?</td>
<td class="notes"><a class="readme-tag" href="https://github.com/DFKHelper/token-goat/blob/main/README.md#what-gets-installed" target="_blank" title="View section in public GitHub README">GitHub README: ## What gets installed? · ## CLI</a><span class="check">✓</span> Token-goat builds a full code relationship graph in SQLite, tracking callers, callees, class inheritance, and refactoring impact without compiling code.</td>
<td><a href="https://github.com/DFKHelper/token-goat/blob/main/src/graph_commands.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/graph_commands.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/parser.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/parser.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/db.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/db.ts</code></a></td>
</tr>
<!-- Accordion Detail Row -->
<tr class="detail-row" id="detail-Q-07" style="display:none;" data-author="graph">
<td colspan="6" style="padding:0; background:var(--surface-2); border-bottom:2px solid var(--border);">
<div class="inline-drawer">
<div class="inline-drawer-header">
<div><strong>Q-07 DETAILED BREAKDOWN</strong> · AUTHOR: <strong>Code Intelligence & AST Lead</strong></div>
<div>REFERENCES (PUBLIC GITHUB): <code style="color:var(--accent); font-weight:600;"><a href="https://github.com/DFKHelper/token-goat/blob/main/src/graph_commands.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/graph_commands.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/parser.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/parser.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/db.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/db.ts</a></code></div>
</div>
<div class="readme-ref-banner">
<span class="readme-badge">PUBLIC GITHUB README</span>
<span>Covered in public GitHub README sections: <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#what-gets-installed" target="_blank">## What gets installed?</a></strong> (Indexed Tables: symbols, docstrings, refs, chunks) and <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#cli" target="_blank">## CLI</a></strong> (refs & semantic)</span>
</div>
<div class="qa-answer-body" id="ans-Q-07">
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 1</span>
<span>What code relationships token-goat tracks</span>
</div>
<div class="sub-answer-text">
<p>Yes, token-goat maintains a complete code relationship graph in its local SQLite database (<code>refs</code> table). It does not just index text; it parses code into syntax trees to track:</p>
<ul>
<li><strong>Callers & Callees:</strong> Which functions call which other functions.</li>
<li><strong>Inheritance:</strong> Which classes <code>extend</code> or <code>implement</code> an interface.</li>
<li><strong>Impact Analysis:</strong> What breaks if you change a function signature.</li>
</ul>
<div class="example-box">
<div class="example-header">Example 1: Find all callers of a function</div>
<span style="color:var(--text-faint);">$</span> token-goat refs "src/auth.ts::validateToken" --callers<br>
<span style="color:var(--text);">Callers of validateToken:</span><br>
1. src/api/middleware.ts:32 (authMiddleware)<br>
2. src/routes/user.ts:18 (getProfile)<br>
3. src/websocket/gateway.ts:54 (onConnect)
</div>
<div class="example-box">
<div class="example-header">Example 2: Check refactoring blast radius</div>
<span style="color:var(--text-faint);">$</span> token-goat impact "src/database.ts::query"<br>
<span style="color:var(--text);">Impact: 14 downstream call sites across 6 files will be affected.</span>
</div>
</div>
</div>
</div>
</div>
</td>
</tr>
<!-- Primary Question Row -->
<tr class="inquiry-row" id="Q-08" data-author="graph" data-qid="Q-08">
<td class="line-id"><span class="toggle-icon">▶</span> Q-08</td>
<td><span class="author-badge">Code Intelligence & AST Lead</span></td>
<td style="font-size:11.5px; color:var(--text-dim); font-weight:500;">MCP & Memory Integration</td>
<td class="field-name">Could Token-Goat be paired with something like MCP codebase-memory, where codebase-memory maps out the relationships and Token-Goat pulls and compresses just the relevant code before it reaches the LLM?</td>
<td class="notes"><a class="readme-tag" href="https://github.com/DFKHelper/token-goat/blob/main/README.md#mcp-server" target="_blank" title="View section in public GitHub README">GitHub README: ## MCP server · ## CLI</a><span class="check">✓</span> Generic MCP memory tools carry schema and JSON overhead per turn. Token-goat-mem is a separate personal OSS project exploring pointer-based memory instead; no comparative measurement between the two has been run or is claimed here (it is also pending IT review, so it is not part of this deployment).</td>
<td><a href="https://github.com/DFKHelper/token-goat/blob/main/src/mcp_server.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/mcp_server.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_compact.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/hooks_compact.ts</code></a><br><a href="https://github.com/DFKHelper/token-goat/blob/main/src/read_commands.ts" target="_blank" class="github-file-link" title="View on public GitHub"><code style="font-family:var(--font-mono); font-size:11px; background:var(--surface-2); padding:2px 6px; border-radius:3px; border:1px solid var(--border); display:inline-block; margin-bottom:3px; color:var(--text);">src/read_commands.ts</code></a></td>
</tr>
<!-- Accordion Detail Row -->
<tr class="detail-row" id="detail-Q-08" style="display:none;" data-author="graph">
<td colspan="6" style="padding:0; background:var(--surface-2); border-bottom:2px solid var(--border);">
<div class="inline-drawer">
<div class="inline-drawer-header">
<div><strong>Q-08 DETAILED BREAKDOWN</strong> · AUTHOR: <strong>Code Intelligence & AST Lead</strong></div>
<div>REFERENCES (PUBLIC GITHUB): <code style="color:var(--accent); font-weight:600;"><a href="https://github.com/DFKHelper/token-goat/blob/main/src/mcp_server.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/mcp_server.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/hooks_compact.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/hooks_compact.ts</a>, <a href="https://github.com/DFKHelper/token-goat/blob/main/src/read_commands.ts" target="_blank" class="github-file-link" style="color:var(--accent); text-decoration:underline;">src/read_commands.ts</a></code></div>
</div>
<div class="readme-ref-banner">
<span class="readme-badge">PUBLIC GITHUB README</span>
<span>Covered in public GitHub README sections: <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#mcp-server" target="_blank">## MCP server</a></strong>, <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#generic-compression-and-handoffs" target="_blank">### Generic compression and handoffs</a></strong>, and <strong><a href="https://github.com/DFKHelper/token-goat/blob/main/README.md#cli" target="_blank">## CLI</a></strong> (Surgical Reads)</span>
</div>
<div class="qa-answer-body" id="ans-Q-08">
<div class="sub-qa-block">
<div class="sub-question-title">
<span class="sub-question-badge">PART 1</span>
<span>The Pairing Concept: Theory vs. Real-World MCP Context Waste</span>
</div>
<div class="sub-answer-text">
<p>In theory, pairing architectural memory with token-goat is a natural division of labor: memory maps relationships, and token-goat extracts the exact code. But in production, running generic <strong>MCP codebase-memory</strong> tools burns massive context through three specific failure modes:</p>
<p><strong>1. The Permanent System Prompt Schema Tax:</strong><br>
Registering an MCP server forces the harness to inject full JSON-schema definitions for every tool into the system prompt on <em>every single turn</em>. Declaring standard memory tools (<code>create_entities</code>, <code>create_relations</code>, <code>add_observations</code>, <code>read_graph</code>, <code>search_nodes</code>) costs on the order of a thousand tokens. In a 20-turn session that whole cost is re-billed every turn, just for the tools to sit idle in context.</p>
<p><strong>2. The JSON Syntax & Entity Dump Tax:</strong><br>
When queried, generic memory servers return sprawling JSON payloads where over 40% of the tokens are syntactic scaffolding (brackets, quotes, property keys):</p>
<div class="example-box">
<div class="example-header">MCP Codebase-Memory Response Payload (abridged; 57% of this excerpt is scaffolding rather than prose)</div>
<pre style="margin:0; font-family:var(--font-mono); font-size:11px; color:var(--text); line-height:1.45; overflow-x:auto;">{
"entities": [
{
"name": "AuthService",
"entityType": "class",
"observations": [
"Handles OAuth2 session refresh and JWT token verification",
"Located in src/auth/service.ts, exported as default class",
"Code snapshot: async refreshSession(token) { const res = await fetch('/oauth/token'); return res.json(); ... [40 lines of static code copied into memory] }"
]
}
],
"relations": [
{"from": "AuthService", "to": "UserController", "relationType": "injected_into"},
{"from": "AuthService", "to": "RedisSessionStore", "relationType": "queries"}
]
}</pre>
</div>