cognitune 0.2.2 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/CHANGELOG.md +55 -0
  2. package/README.md +184 -41
  3. package/SETUP.md +111 -0
  4. package/dist/cli.js +161 -21
  5. package/dist/web/assets/Map-xBJDQ_Xn.js +1 -0
  6. package/dist/web/assets/{Practice-Xw4Aap9n.js → Practice-DNf-tMjl.js} +3 -3
  7. package/dist/web/assets/{_baseUniq-Sb6_kXmC.js → _baseUniq-7KLmbwxc.js} +1 -1
  8. package/dist/web/assets/{architectureDiagram-UYN6MBPD-x3eTjV-t.js → architectureDiagram-UYN6MBPD-DFK-K3Yp.js} +1 -1
  9. package/dist/web/assets/{blockDiagram-ZHA2E4KO-agwz5ZWE.js → blockDiagram-ZHA2E4KO-D9jSBc-F.js} +1 -1
  10. package/dist/web/assets/{c4Diagram-6F5ED5ID-CJxB9Ung.js → c4Diagram-6F5ED5ID-KAOALvx3.js} +1 -1
  11. package/dist/web/assets/channel-BW4MllLS.js +1 -0
  12. package/dist/web/assets/{chunk-5HRBRIJM-f0vN99nH.js → chunk-5HRBRIJM-Btr12S8H.js} +1 -1
  13. package/dist/web/assets/{chunk-7U56Z5CX-BM--ABPc.js → chunk-7U56Z5CX-NWMyaEQ0.js} +1 -1
  14. package/dist/web/assets/{chunk-ASOPGD6M-CR8uj1YE.js → chunk-ASOPGD6M-DdvxpUSZ.js} +1 -1
  15. package/dist/web/assets/{chunk-KFBOBJHC-5IsURXrq.js → chunk-KFBOBJHC-CLK5Qods.js} +1 -1
  16. package/dist/web/assets/{chunk-T2TOU4HS-Byx0enoR.js → chunk-T2TOU4HS-B-nrzheR.js} +1 -1
  17. package/dist/web/assets/{chunk-TMUBEWPD-BIF411CX.js → chunk-TMUBEWPD-DCsdC8PC.js} +1 -1
  18. package/dist/web/assets/classDiagram-LNE6IOMH-D4kEJsvG.js +1 -0
  19. package/dist/web/assets/classDiagram-v2-MQ7JQ4JX-D4kEJsvG.js +1 -0
  20. package/dist/web/assets/clone-C8mTbP7R.js +1 -0
  21. package/dist/web/assets/{dagre-4EVJKHTY-1RD8lskl.js → dagre-4EVJKHTY-D_09gC0H.js} +1 -1
  22. package/dist/web/assets/{diagram-QW4FP2JN-PO1Q65My.js → diagram-QW4FP2JN-quH5WQny.js} +1 -1
  23. package/dist/web/assets/{erDiagram-6RL3IURR-Cr2hBiWe.js → erDiagram-6RL3IURR-BmJHLDew.js} +1 -1
  24. package/dist/web/assets/{flowDiagram-7ASYPVHJ-ClDedrj1.js → flowDiagram-7ASYPVHJ-DNzT7Cua.js} +1 -1
  25. package/dist/web/assets/{ganttDiagram-NTVNEXSI-D13tzRyI.js → ganttDiagram-NTVNEXSI-6reJ1AIG.js} +1 -1
  26. package/dist/web/assets/{gitGraph-YCYPL57B-BsavMmM6.js → gitGraph-YCYPL57B-BfipSUJ3.js} +1 -1
  27. package/dist/web/assets/{gitGraphDiagram-NRZ2UAAF-DIucBoe8.js → gitGraphDiagram-NRZ2UAAF-BRb9bqzI.js} +1 -1
  28. package/dist/web/assets/{graph-CClVjaHZ.js → graph-BHXuL-RR.js} +1 -1
  29. package/dist/web/assets/{index-DBSUkj1m.js → index-7JDqNzz1.js} +1 -1
  30. package/dist/web/assets/{index-B3eGs35g.js → index-B49g1XNF.js} +1 -1
  31. package/dist/web/assets/{index-D91GOqgw.js → index-B5Tomqy6.js} +1 -1
  32. package/dist/web/assets/{index-D45gW5O5.js → index-BCM7jSxq.js} +1 -1
  33. package/dist/web/assets/{index-DRtWlWMo.js → index-BM9KwSU5.js} +1 -1
  34. package/dist/web/assets/{index-CS1X9Gl5.js → index-BiiiKqbq.js} +1 -1
  35. package/dist/web/assets/{index-2r9n9DTs.js → index-Bli4383n.js} +1 -1
  36. package/dist/web/assets/{index-CMZRuo_o.js → index-BsH1Ca5H.js} +1 -1
  37. package/dist/web/assets/{index-BqYXODG4.js → index-Bsf4UF_h.js} +1 -1
  38. package/dist/web/assets/{index-DxsK976j.js → index-C5JoMvch.js} +1 -1
  39. package/dist/web/assets/{index-DkYraAal.js → index-C67RtHfG.js} +1 -1
  40. package/dist/web/assets/{index-DDrV_F4m.js → index-CNViI9C2.js} +1 -1
  41. package/dist/web/assets/{index-BOSsA0NJ.js → index-CQjof-kk.js} +1 -1
  42. package/dist/web/assets/{index-ByIxB7D0.js → index-CyHGDhfc.js} +1 -1
  43. package/dist/web/assets/index-CyhIx47s.css +1 -0
  44. package/dist/web/assets/{index-B_vWzZYC.js → index-D-DY42g9.js} +1 -1
  45. package/dist/web/assets/{index-Cv-pFH6x.js → index-DRri1mnd.js} +1 -1
  46. package/dist/web/assets/{index-o9r5KATO.js → index-DXji-ikE.js} +1 -1
  47. package/dist/web/assets/{index-SjGg9_vE.js → index-D_DIS1os.js} +1 -1
  48. package/dist/web/assets/{index-DUIbUB4M.js → index-Dl6tJxzv.js} +1 -1
  49. package/dist/web/assets/{index-eIlS8nUF.js → index-TI1LWXRL.js} +1 -1
  50. package/dist/web/assets/index-dA5Y-R2D.js +514 -0
  51. package/dist/web/assets/{index-6LcRt5Lv.js → index-wnqHtEcu.js} +1 -1
  52. package/dist/web/assets/{index-Dls_C4WS.js → index-ysHMZpcw.js} +1 -1
  53. package/dist/web/assets/{infoDiagram-A4XQUW5V-DAnVWlAh.js → infoDiagram-A4XQUW5V-CE9eDiRA.js} +1 -1
  54. package/dist/web/assets/{journeyDiagram-G5WM74LC-pfkLfgwO.js → journeyDiagram-G5WM74LC-D_iPCzBK.js} +1 -1
  55. package/dist/web/assets/{kanban-definition-QRCXZQQD-ntmo18GF.js → kanban-definition-QRCXZQQD-Bxj-EOmZ.js} +1 -1
  56. package/dist/web/assets/{layout-B4CWy8Hm.js → layout-CQ6J22ew.js} +1 -1
  57. package/dist/web/assets/layout.worker-Bzrmqu8H.js +1 -0
  58. package/dist/web/assets/{mermaid.core-lBUDS75V.js → mermaid.core-27sLJoRM.js} +4 -4
  59. package/dist/web/assets/{min-DbZdLDS_.js → min-h0zR_W4w.js} +1 -1
  60. package/dist/web/assets/{mindmap-definition-GWI6TPTV-Bl9WyGjM.js → mindmap-definition-GWI6TPTV-DiBTVWc8.js} +28 -28
  61. package/dist/web/assets/{pieDiagram-YF2LJOPJ-DnH09lh-.js → pieDiagram-YF2LJOPJ-BE2VMHC3.js} +1 -1
  62. package/dist/web/assets/{quadrantDiagram-OS5C2QUG-BxEAU4LU.js → quadrantDiagram-OS5C2QUG-DkN-8Avj.js} +1 -1
  63. package/dist/web/assets/{requirementDiagram-MIRIMTAZ-QAvHb6Mc.js → requirementDiagram-MIRIMTAZ-0OCRbKti.js} +1 -1
  64. package/dist/web/assets/{sankeyDiagram-Y46BX6SQ-eS48EBnq.js → sankeyDiagram-Y46BX6SQ-6v9qBJFv.js} +1 -1
  65. package/dist/web/assets/{sequenceDiagram-G6AWOVSC-CzMqlsbJ.js → sequenceDiagram-G6AWOVSC-CjH7axp-.js} +1 -1
  66. package/dist/web/assets/{stateDiagram-MAYHULR4-xkap43Xx.js → stateDiagram-MAYHULR4-Bbbno_Ix.js} +1 -1
  67. package/dist/web/assets/stateDiagram-v2-4JROLMXI-CvrRdVH2.js +1 -0
  68. package/dist/web/assets/{timeline-definition-U7ZMHBDA-BAuokBbp.js → timeline-definition-U7ZMHBDA-BSIsFSlr.js} +1 -1
  69. package/dist/web/assets/{xychartDiagram-6QU3TZC5-Cnc3AQRt.js → xychartDiagram-6QU3TZC5-B12dxFiy.js} +1 -1
  70. package/dist/web/index.html +2 -2
  71. package/package.json +2 -1
  72. package/dist/web/assets/Map-DyU40kFC.js +0 -1
  73. package/dist/web/assets/channel-BBLQ9UF8.js +0 -1
  74. package/dist/web/assets/classDiagram-LNE6IOMH-BtyOxYYt.js +0 -1
  75. package/dist/web/assets/classDiagram-v2-MQ7JQ4JX-BtyOxYYt.js +0 -1
  76. package/dist/web/assets/clone-qT-pKr2u.js +0 -1
  77. package/dist/web/assets/index-Biw9rLAa.css +0 -1
  78. package/dist/web/assets/index-ChTnBaTd.js +0 -493
  79. package/dist/web/assets/stateDiagram-v2-4JROLMXI-T7PcvgVe.js +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,60 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.1 (2026-11-18)
4
+
5
+ New:
6
+
7
+ - **Progress rolls up by repo and folder.** At a folder of many repos, each repo is one row with a
8
+ coverage bar; click to go into its folders, then files. A scope bar (breadcrumb with a repo picker)
9
+ narrows the cards, table and heatmap, and search filters the touched files in it. The scope lives
10
+ in the address, so it can be bookmarked. Untouched rows fold into one "show N untouched" line.
11
+ - **Map shows repos and folders, not ~2,000 files.** Nodes are repos, then folders, then files at
12
+ the current scope; a folder of 8 code files or fewer shows its files. Imports between two folders
13
+ are one arrow, thicker for more imports, so a Python package's `__init__.py` no longer looks like a
14
+ hub. Click a folder to go in. The layout runs off the main thread behind a placeholder map, and the
15
+ server keeps the graph until you press Refresh (it used to rebuild every minute).
16
+ - README: a banner, the Read / Prove / Keep loop, and screenshots cropped to be readable.
17
+
18
+ Fixes:
19
+
20
+ - Tutor links dropped the word between two ranges: "lines 41-48 and 58-60" showed as "41-4858-60".
21
+ - The Today page's path card said "Do this stop"; it now names the activity ("Start the lens"),
22
+ like the Paths page.
23
+ - The Library's tab strip stretches to fill its row instead of ending in an empty block.
24
+
25
+ ## 0.3.0 (2026-11-18)
26
+
27
+ New:
28
+
29
+ - **Lens follow-ups.** "Ask more about this" at the end of a lens adds the answer to the same
30
+ lens instead of making a new one. Ticked files can come along as extra context; new terms and
31
+ gotchas join the lens's lists, and the markdown export includes the follow-ups.
32
+ - **Weak spots page.** A Weak spots tab in the Library: quiz yourself on one weak spot, or
33
+ dismiss one the grader got wrong. Today links to it.
34
+ - **Walk "Try again".** A block you didn't get right can be answered again; a right answer
35
+ clears its weak spot.
36
+ - **Jobs in the status bar.** Running jobs show at the bottom of the window, and a job that
37
+ finishes after you left its page shows a "ready · open" link.
38
+ - **Tutor chat** is restyled as chat bubbles with timestamps, and "line 42" / "lines 64-71" in a
39
+ hint jump the code pane to those lines.
40
+ - Teach-back and the tutor, started from the Changes page, now see the diff (only lens and quiz
41
+ did before). The tutor sees it on every turn.
42
+ - A review card links back to the lens or quiz it came from.
43
+ - `.claude` folders show in the Explore file tree, so session notes can be ticked as context.
44
+
45
+ Fixes:
46
+
47
+ - The tutor's replies rendered at 17px next to 14px user messages: the serif reading-font rule
48
+ out-ranked the chat styles. Both now match.
49
+ - The lens page flickered while a job ran: every mermaid diagram and code block was remounted
50
+ twice a second. Markdown rendering now keeps them mounted.
51
+ - Syntax highlighting now works in the Changes diff view, in fenced code blocks inside lens and
52
+ quiz prose, and in bug hunt's code copy (each was plain text before, for different reasons).
53
+ - File-chip lists on the quiz, teach-back and tutor pages collapse to 6 + "N more", like the
54
+ lens page.
55
+ - The Library's tabs fit on one row instead of scrolling sideways (a narrow window wraps them),
56
+ and a path stop's button says what it starts ("Start the lens") instead of "Do this stop".
57
+
3
58
  ## 0.2.2 (2026-11-10)
4
59
 
5
60
  Release workflow fix, no feature changes:
package/README.md CHANGED
@@ -1,61 +1,193 @@
1
- # cognitune
2
-
3
- Understand any codebase, and prove to yourself that you do.
4
-
5
- AI makes code faster to write and easier to not understand. cognitune turns the model around: instead of
6
- writing code for you, it helps you build the model of the code in your own head.
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/banner-dark.svg">
4
+ <img alt="cognitune. Understand any codebase, and prove to yourself that you do." src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/banner-light.svg" width="860">
5
+ </picture>
6
+ </p>
7
+
8
+ <p align="center">
9
+ <a href="https://www.npmjs.com/package/cognitune"><img alt="npm" src="https://img.shields.io/npm/v/cognitune?color=268bd2"></a>
10
+ <img alt="node 20 or newer" src="https://img.shields.io/badge/node-%3E%3D20-859900">
11
+ <img alt="MIT license" src="https://img.shields.io/badge/license-MIT-b58900">
12
+ <img alt="runs locally" src="https://img.shields.io/badge/runs-locally-586e75">
13
+ </p>
14
+
15
+ <p align="center">
16
+ <a href="#try-it-in-a-minute"><b>Try it</b></a> ·
17
+ <a href="#what-you-do-in-it"><b>What you do in it</b></a> ·
18
+ <a href="#why-it-works"><b>Why it works</b></a> ·
19
+ <a href="SETUP.md"><b>Setup</b></a> ·
20
+ <a href="CHANGELOG.md"><b>Changelog</b></a>
21
+ </p>
22
+
23
+ AI makes code faster to write and easier to not understand.
24
+ **cognitune turns the model around: it does not write code for you. It teaches you the code you have, then checks that you got it.**
25
+
26
+ ## Try it in a minute
7
27
 
8
28
  ```bash
9
- npx cognitune ./my-repo
10
- npx cognitune --demo # a sample repo and canned answers: see every page in a minute, no model needed
29
+ npx cognitune --demo # a sample repo with canned answers. No model, no login.
30
+ npx cognitune ./my-repo # your own code, with the coding CLI you already use
11
31
  ```
12
32
 
13
- | | |
14
- |---|---|
15
- | ![Open a folder](assets/screenshots/projects.png) | ![A lens over real code](assets/screenshots/lens.png) |
16
- | ![The import graph](assets/screenshots/map.png) | ![Progress per file](assets/screenshots/progress.png) |
33
+ - **No new account, no key.** It runs Claude Code, Codex or Copilot with that CLI's own login.
34
+ - **Read-only.** It works from the files you tick, and cognitune never writes to your folders.
35
+ - **Local.** A web app on `127.0.0.1`. Your notes and scores are plain JSON files in `~/.cognitune`.
17
36
 
18
- ## What it does
37
+ <p align="center">
38
+ <picture>
39
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/lens-dark.png">
40
+ <img alt="A lens about a retry queue: the idea in one sentence, why it matters, then the words you need first" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/lens.png" width="860">
41
+ </picture>
42
+ <br>
43
+ <sub>A lens: one question, answered about the files you picked. The screenshots are real model output on the bundled 100-line demo repo (Map and Progress show cognitune's own source).</sub>
44
+ </p>
19
45
 
20
- It is built on what makes learning stick: recall beats re-reading, spacing beats cramming, and
21
- producing an answer before you see one beats reading the answer.
46
+ ## What you do in it
22
47
 
23
- **Read, with a question**
48
+ <p align="center">
49
+ <picture>
50
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/loop-dark.svg">
51
+ <img alt="The loop: 1. Read with a question (lens, tutor, walkthrough). 2. Prove it (quiz, teach-back, practice, bug hunt). 3. Keep it (review cards, weak spots, today). What you got wrong comes back." src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/loop-light.svg" width="860">
52
+ </picture>
53
+ </p>
54
+
55
+ ### 1. Read with a question
24
56
 
25
57
  | | |
26
58
  |---|---|
27
- | **Lenses** | See code through one question: *Explain*, *Data flow*, *State over time*, *Failure modes*, *Contracts*, *Concepts*, *The change*, *Trace a run* (a debugger without running: line by line with the variables), *History* (why it is like this, from git), or your own. Tick **My take first** to write your own guess before the lens; it opens with where you differ. On a diff, that becomes **Predict first**. A lens shows a banner when its code changes, with one-click refresh. |
28
- | **Walkthrough** | The file in reading order (not file order), one block at a time, with a check question on each block before the next. |
29
- | **Tutor** | A Socratic chat over the files. It answers with a question or a hint first and gives a bit more each turn; ask it to just tell you any time. Opens from any missed quiz question too. |
30
- | **Map** | The import graph (TS/JS with tsconfig aliases, Python), sized by how many files import each one: where to start. |
31
- | **Paths** | An ordered tour of the repo, 6-12 stops, each with the activity that fits. Stops tick off as you do them. |
59
+ | **Lens** | Pick files, pick a question: *Explain*, *Data flow*, *Failure modes*, *Trace a run*, *History*, or your own. You get a lesson where every step shows its own lines of code. Ask a follow-up and the answer joins the same lens. |
60
+ | **Tutor** | A Socratic chat. It gives a nudge first, then a hint, then more. Say "just tell me" any time. Click "line 50" in a reply and the code pane jumps there. |
61
+ | **Walkthrough** | The file in reading order, one block at a time. Each block ends with a question you answer before you go on. |
62
+
63
+ <p align="center">
64
+ <img alt="The tutor answers with a nudge, then a hint. Line numbers in its replies are links into the code pane on the right." src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/tutor.png" width="860">
65
+ <br>
66
+ <sub><b>Tutor.</b> A nudge, then a hint. The blue line numbers jump the code pane.</sub>
67
+ </p>
68
+
69
+ <table>
70
+ <tr>
71
+ <td width="50%"><img alt="A follow-up question answered inside the same lens, with file and line references" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/followup.png"></td>
72
+ <td width="50%"><img alt="A walkthrough block: worked example, a check question, the answer typed and the feedback" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/walk.png"></td>
73
+ </tr>
74
+ <tr>
75
+ <td align="center"><sub><b>Follow-up.</b> Ask more; the answer is added to the lens.</sub></td>
76
+ <td align="center"><sub><b>Walkthrough.</b> Answer the check, then the next block.</sub></td>
77
+ </tr>
78
+ </table>
79
+
80
+ ### 2. Prove it
32
81
 
33
- **Prove it**
82
+ | | |
83
+ |---|---|
84
+ | **Quiz** | Free-text questions about behaviour and reasons, not names. Mark each answer *sure* or *guess*. The feedback names the line you got wrong. A wrong answer you were sure of is flagged first. |
85
+ | **Teach-back** | Explain the code in your own words. Graded 1-5: what is right, what is missing, what is wrong. |
86
+ | **Practice** | The key logic is cut out of a copy of your file. Write it back, with hints. |
87
+ | **Bug hunt** | Bugs are planted in a copy of the file. Find them and say why. |
88
+ | **Changes** | A split diff of two git refs, or of your uncommitted work. Every activity above can run on the diff. Good before you merge code you did not write. |
89
+
90
+ <p align="center">
91
+ <img alt="A graded quiz: score, the question, the answer marked sure, feedback that corrects two line numbers, and a good answer to compare with" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/quiz.png" width="860">
92
+ <br>
93
+ <sub><b>Quiz.</b> The answer was right, the line numbers were off, and the feedback says so.</sub>
94
+ </p>
95
+
96
+ <table>
97
+ <tr>
98
+ <td width="50%"><img alt="Practice: two holes cut out of fail() in queue.ts, the hole's intent on the right, and Check my work" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/practice.png"></td>
99
+ <td width="50%"><img alt="A graded bug hunt: one planted bug found with the reason, one missed, the buggy and real lines side by side" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/hunt.png"></td>
100
+ </tr>
101
+ <tr>
102
+ <td align="center"><sub><b>Practice.</b> Write the missing logic back, then check your work.</sub></td>
103
+ <td align="center"><sub><b>Bug hunt.</b> Found, missed and false alarms, each explained.</sub></td>
104
+ </tr>
105
+ </table>
106
+
107
+ <p align="center">
108
+ <img alt="The Changes page: file list, a split diff of an uncommitted change, and the activities that can run on it" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/changes.png" width="860">
109
+ <br>
110
+ <sub><b>Changes.</b> Read the diff, then lens it, quiz yourself on it or ask the tutor about it.</sub>
111
+ </p>
112
+
113
+ ### 3. Keep it
34
114
 
35
115
  | | |
36
116
  |---|---|
37
- | **Quizzes** | Free-text questions about behaviour and reasons, not names. Mark each answer *sure* or *guess*. Graded with feedback that names the line and a good answer to compare with. |
38
- | **Teach-back** | Explain the code in your own words. Graded 1-5: what you got right, what you missed, what is wrong. |
39
- | **Practice** | The key logic is cut out of a copy of your file (4 levels). Write it back, with hints, then "check my work". |
40
- | **Bug hunt** | Realistic bugs are planted in a copy of the file. Click the lines you suspect and say why; see found, missed and false alarms. |
41
- | **Changes** | Two git refs, or HEAD vs your working tree. Read the diff, then predict, lens or quiz the change itself. |
117
+ | **Weak spots** | A wrong answer is saved as the belief behind it: "you think X, but Y". The next quiz aims at exactly those. A right answer clears one. |
118
+ | **Review cards** | Quiz misses become spaced-repetition cards (FSRS). Each card links back to the quiz or lens it came from. |
119
+ | **Today** | Each project opens on what to do now: cards due, weak spots, files that changed, the next stop on your path. |
120
+ | **Map, Paths, Progress** | See how the repo hangs together, take an ordered tour of it, and see what you have proved and what is fading. |
121
+
122
+ <table>
123
+ <tr>
124
+ <td width="50%"><img alt="Today: a suggested next step, 2 review cards due, two weak spots written as beliefs, and the next learning path stop" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/today.png"></td>
125
+ <td width="50%"><img alt="A review card made from a quiz miss: the question, what you wrote, the answer, and the Again, Hard, Good, Easy buttons" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/review.png"></td>
126
+ </tr>
127
+ <tr>
128
+ <td align="center"><sub><b>Today.</b> What to do now, in about 10 minutes.</sub></td>
129
+ <td align="center"><sub><b>Review.</b> Recall first, then reveal and rate.</sub></td>
130
+ </tr>
131
+ <tr>
132
+ <td width="50%"><img alt="The map: folders sized by their files, thicker arrows for more imports between them" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/map.png"></td>
133
+ <td width="50%"><img alt="Progress: folders rolled up with coverage bars, and cards for understood, fading, stale and seen" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/progress.png"></td>
134
+ </tr>
135
+ <tr>
136
+ <td align="center"><sub><b>Map.</b> Repos and folders, then files. Click a folder to go in.</sub></td>
137
+ <td align="center"><sub><b>Progress.</b> Per repo, folder and file: proved, fading or stale.</sub></td>
138
+ </tr>
139
+ </table>
140
+
141
+ ## Use it when
142
+
143
+ - You joined a team and must find your way in a repo you did not write.
144
+ - An agent wrote the code and you must own it. Open **Changes** and quiz yourself on the diff.
145
+ - You come back to your own code after six months.
146
+ - You review a pull request and want to know what it does, not only that it looks fine.
147
+
148
+ ## Why it works
149
+
150
+ Three findings from learning research decide how every page behaves.
151
+
152
+ | The finding | What cognitune does about it |
153
+ |---|---|
154
+ | **Recall beats re-reading** | Quizzes and teach-back are free text. You write the answer; you do not pick it from a list. |
155
+ | **Spacing beats cramming** | Misses come back as review cards on a schedule. Progress marks a file *fading* when you stop recalling it. |
156
+ | **Answer first, then read** | The tutor hints before it tells. A lens can ask for your own take first. A missed check asks you to try again. |
157
+
158
+ ## Reference
42
159
 
43
- **Keep it**
160
+ <details>
161
+ <summary><b>All features</b></summary>
162
+ <br>
44
163
 
45
164
  | | |
46
165
  |---|---|
166
+ | **Lenses** | See code through one question: *Explain*, *Data flow*, *State over time*, *Failure modes*, *Contracts*, *Concepts*, *The change*, *Trace a run* (a debugger without running: line by line with the variables), *History* (why it is like this, from git), or your own. Tick **My take first** to write your own guess before the lens; it opens with where you differ. On a diff, that becomes **Predict first**. Ask follow-ups at the end; the answers are added to the same lens. A lens shows a banner when its code changes, with one-click refresh. |
167
+ | **Walkthrough** | The file in reading order (not file order), one block at a time, with a check question on each block before the next. Retry a block you missed. |
168
+ | **Tutor** | A Socratic chat over the files. It answers with a question or a hint first and gives a bit more each turn; ask it to just tell you any time. Line references jump the code pane. |
169
+ | **Map** | The import graph (TS/JS with tsconfig aliases, Python) at one scope: repos, then folders, then files. Thicker arrows carry more imports; click a folder to go in. A folder of 8 code files or fewer shows its files. |
170
+ | **Paths** | An ordered tour of the repo, 6-12 stops, each with the activity that fits. Stops tick off as you do them. |
171
+ | **Quizzes** | Free-text questions about behaviour and reasons, not names. Mark each answer *sure* or *guess*. Graded with feedback that names the line and a good answer to compare with. |
172
+ | **Teach-back** | Explain the code in your own words. Graded 1-5: what you got right, what you missed, what is wrong. |
173
+ | **Practice** | The key logic is cut out of a copy of your file (4 levels). Write it back, with hints, then "check my work". |
174
+ | **Bug hunt** | Realistic bugs are planted in a copy of the file. Click the lines you suspect and say why; see found, missed and false alarms. |
175
+ | **Changes** | Two git refs, or HEAD vs your working tree. Read the diff, then predict, lens, quiz, teach back or ask the tutor about the change itself. |
47
176
  | **Review cards** | Spaced repetition (FSRS). Quiz misses become cards on their own; lens concepts and code lines can become cards in one click. |
48
- | **Weak spots** | Wrong answers are saved as the belief behind them ("you think X, but Y"). *Quiz my weak spots* asks new questions aimed at exactly those; a right answer clears one. |
49
- | **Today** | Each project opens on what to do now: due cards, weak spots, files that need a refresh, the next stop on your path, and one suggested 10-minute activity. |
50
- | **Progress** | Per file: *seen*, *understood* (a check passed on the code as it is now), *fading* (no recall for a few weeks), *stale* (the code changed since). Table, or a heatmap of the whole repo. |
51
- | **Library** | Everything made, searchable, plus a glossary built from every lens and your margin notes. Export a lens or quiz as markdown, or a whole project as JSON. |
52
-
53
- `Ctrl/Cmd+K` jumps to any page, file or project, or starts an activity. `?` lists all shortcuts.
177
+ | **Weak spots** | Wrong answers are saved as the belief behind them. Quiz one weak spot or all of them; a right answer clears one; dismiss one the grader got wrong. |
178
+ | **Today** | Due cards, weak spots, files that need a refresh, the next stop on your path, and one suggested 10-minute activity. |
179
+ | **Progress** | Rolled up per repo and folder, then per file: *seen*, *understood* (a check passed on the code as it is now), *fading* (no recall for a few weeks), *stale* (the code changed since). Pick a repo, drill into folders, search; table or heatmap. |
180
+ | **Library** | Everything made, searchable, plus a glossary and your margin notes. Export a lens or quiz as markdown, or a whole project as JSON. |
54
181
 
55
182
  Context is what you pick: tick files in the tree, or add extra folders (docs, notes, design files) to a
56
- project as context. The model reads only what you give it.
183
+ project as context. The model works from what you give it. Long jobs keep running if you leave the page;
184
+ the status bar says when they are ready. <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>K</kbd> jumps anywhere; <kbd>?</kbd> lists shortcuts.
185
+
186
+ </details>
57
187
 
58
- ## Model access
188
+ <details>
189
+ <summary><b>Model access</b>: Claude Code, Codex, Copilot or the Anthropic API</summary>
190
+ <br>
59
191
 
60
192
  cognitune makes one model call per lens, quiz, grade, practice, tutor turn and so on (about 15 s to 2 min).
61
193
  Replies are checked against a schema (one retry with the problems listed), and lens, walkthrough and path
@@ -73,9 +205,16 @@ stores a key**. Pick one in Settings; *Auto* takes the first one it finds, in th
73
205
  Each CLI runs with the project folder as its working directory. Model per provider is optional
74
206
  (empty = the CLI's default). `COGNITUNE_AGENT=fake` gives canned answers, to try the UI without a model.
75
207
 
76
- ## Your files are safe
208
+ Step-by-step setup: [SETUP.md](SETUP.md).
209
+
210
+ </details>
211
+
212
+ <details>
213
+ <summary><b>Your files are safe</b>: local only, read-only, bounded storage</summary>
214
+ <br>
77
215
 
78
216
  - cognitune never writes to your folders. Practice works on a copy.
217
+ - The server binds to `127.0.0.1` only. There is no login: it is a local, one-person tool.
79
218
  - Everything it makes lives in `~/.cognitune` (change with `COGNITUNE_HOME`), as plain JSON files, one
80
219
  per item. Files, not SQLite: the data is small, you can read and back it up, and there is no native
81
220
  module to build.
@@ -102,16 +241,16 @@ sizes and has *Clean up now*):
102
241
 
103
242
  Cleanup runs at start-up and every 6 hours, and only ever inside the cognitune folder.
104
243
 
105
- - The server binds to `127.0.0.1` only. There is no login: it is a local, one-person tool.
244
+ </details>
106
245
 
107
- ## CLI
246
+ <details>
247
+ <summary><b>CLI and development</b></summary>
248
+ <br>
108
249
 
109
250
  ```
110
251
  cognitune [folder] [--port 4711] [--host 127.0.0.1] [--no-open] [--demo]
111
252
  ```
112
253
 
113
- ## Develop
114
-
115
254
  ```bash
116
255
  npm install
117
256
  npm run dev # API on :4711 (tsx watch) + Vite on :5173 with hot reload
@@ -138,6 +277,10 @@ web/src/ React + Vite + Tailwind: pages/, components/, lib/
138
277
  Stack: TypeScript everywhere. Hono on Node 20+, zod, ts-fsrs. React 18, React Router, TanStack Query,
139
278
  Tailwind, Shiki (code), CodeMirror (practice editor), Mermaid (diagrams), d3-force (map).
140
279
 
280
+ </details>
281
+
141
282
  ## License
142
283
 
143
284
  MIT
285
+
286
+ <p align="center"><sub>If cognitune helped you understand something, <a href="https://github.com/k-pulkit/cognitune/issues">tell me what you would change</a>.</sub></p>
package/SETUP.md ADDED
@@ -0,0 +1,111 @@
1
+ # Setup
2
+
3
+ ## 1. Install
4
+
5
+ ```bash
6
+ # No install — always runs the latest published version
7
+ npx cognitune ./my-repo
8
+
9
+ # Or install once, then just run `cognitune` from anywhere
10
+ npm install -g cognitune
11
+ ```
12
+
13
+ Needs Node >= 20 (`node -v` to check).
14
+
15
+ ## 2. Pick a model backend
16
+
17
+ cognitune drives a coding CLI you already use — it never asks for or stores a key itself. It
18
+ picks the first one it finds, in this order, or you can pin one in Settings:
19
+
20
+ | Backend | One-time setup | Used as |
21
+ |---|---|---|
22
+ | Claude Code (default) | already logged into `claude` | `claude -p`, read-only tools |
23
+ | OpenAI Codex | `codex login` | `codex exec -`, sandboxed read-only |
24
+ | GitHub Copilot | Copilot login, or `export COPILOT_GITHUB_TOKEN=...` | `copilot -p -s`, read-only |
25
+ | Anthropic API directly | `export ANTHROPIC_API_KEY=...` | Messages API |
26
+
27
+ No model set up yet? Run with `--demo` first — canned answers, no login needed, good for a
28
+ first look at every page.
29
+
30
+ ## 3. Run it on a project
31
+
32
+ Say your code lives under a workspace folder, like:
33
+
34
+ ```
35
+ ~/repos/
36
+ ├── awesome-app/
37
+ │ ├── src/
38
+ │ └── package.json
39
+ └── another-project/
40
+ ```
41
+
42
+ Point cognitune at the one you want to understand:
43
+
44
+ ```bash
45
+ cd ~/repos/awesome-app
46
+ cognitune . # opens the browser automatically at http://127.0.0.1:4711
47
+
48
+ # or from anywhere, without cd'ing in first:
49
+ cognitune ~/repos/awesome-app
50
+ ```
51
+
52
+ Your source files are only ever read, never written — practice and bug-hunt exercises work on
53
+ a throwaway copy.
54
+
55
+ ### CLI flags
56
+
57
+ ```
58
+ cognitune [folder] [--port 4711] [--host 127.0.0.1] [--no-open] [--demo]
59
+ ```
60
+
61
+ ## 4. Shell shortcut
62
+
63
+ The CLI is already just `cognitune`, so the shortcut worth having is "run it on wherever I
64
+ currently am":
65
+
66
+ ```bash
67
+ # ~/.bashrc (or ~/.zshrc)
68
+ alias cg='cognitune .'
69
+ ```
70
+
71
+ ```bash
72
+ cd ~/repos/awesome-app && cg
73
+ ```
74
+
75
+ ## 5. Where your data lives
76
+
77
+ Everything cognitune makes is plain JSON files under one home folder — nothing is written
78
+ anywhere else on disk:
79
+
80
+ ```
81
+ ~/.cognitune/ (change with COGNITUNE_HOME)
82
+ ├── settings.json model backend, storage limits
83
+ ├── projects.json known projects (path, id, last opened)
84
+ ├── cache/ model replies, reused on an unchanged file
85
+ ├── archive/ forgotten projects (kept storage.archiveDays, default 30)
86
+ └── projects/
87
+ └── <project-id>/
88
+ ├── lenses/ one file per lens you've made
89
+ ├── quizzes/
90
+ ├── practice/
91
+ ├── teachbacks/
92
+ ├── hunts/ bug-hunt exercises
93
+ ├── walks/ walkthrough progress
94
+ ├── threads/ tutor chat history
95
+ ├── cards/ spaced-repetition review cards
96
+ ├── misconceptions/ weak-spot beliefs behind wrong answers
97
+ ├── notes/ margin notes pinned to lines
98
+ ├── paths/ learning-path progress
99
+ ├── contexts/ extra folders added to this project
100
+ └── archive/ this project's own deleted items
101
+ ```
102
+
103
+ Settings > Storage shows the size of each folder and has a one-click cleanup; nothing grows
104
+ without a cap (see the README's "Your files are safe" section for the exact limits).
105
+
106
+ ## Troubleshooting
107
+
108
+ - **Port already in use** — `cognitune --port 4799` (or whatever's free).
109
+ - **"No model found"** — none of the four backends above are set up; use `--demo` to confirm
110
+ the UI itself works, then set one up.
111
+ - **Try it with no real project yet** — `cognitune --demo` opens a small bundled sample repo.