agent-diary 4.3.0__tar.gz → 4.4.0__tar.gz

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 (103) hide show
  1. {agent_diary-4.3.0 → agent_diary-4.4.0}/.codex-plugin/plugin.json +1 -1
  2. {agent_diary-4.3.0 → agent_diary-4.4.0}/CHANGELOG.md +34 -0
  3. {agent_diary-4.3.0 → agent_diary-4.4.0}/PKG-INFO +37 -13
  4. {agent_diary-4.3.0 → agent_diary-4.4.0}/README.en.md +35 -12
  5. {agent_diary-4.3.0 → agent_diary-4.4.0}/README.md +35 -12
  6. {agent_diary-4.3.0 → agent_diary-4.4.0}/pyproject.toml +17 -2
  7. {agent_diary-4.3.0 → agent_diary-4.4.0}/skills/diary-notion/SKILL.md +1 -1
  8. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/agent_diary.egg-info/PKG-INFO +37 -13
  9. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/agent_diary.egg-info/requires.txt +1 -0
  10. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/__init__.py +1 -1
  11. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/__init__.py +5 -5
  12. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/config.py +2 -2
  13. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_push/__init__.py +55 -5
  14. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_push/ordinals.py +11 -6
  15. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_push/properties.py +9 -1
  16. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_push/validate.py +14 -1
  17. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/setup.py +1 -1
  18. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/write.py +1 -1
  19. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/core.py +8 -5
  20. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/dashboard.py +1 -1
  21. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/formatter.py +8 -3
  22. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/lib/git_info.py +12 -7
  23. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/lib/secret_scanner.py +9 -2
  24. agent_diary-4.4.0/src/claude_diary/types.py +138 -0
  25. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_cli.py +3 -3
  26. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_notion_push.py +114 -0
  27. agent_diary-4.3.0/src/claude_diary/types.py +0 -63
  28. {agent_diary-4.3.0 → agent_diary-4.4.0}/LICENSE +0 -0
  29. {agent_diary-4.3.0 → agent_diary-4.4.0}/MANIFEST.in +0 -0
  30. {agent_diary-4.3.0 → agent_diary-4.4.0}/SECURITY.md +0 -0
  31. {agent_diary-4.3.0 → agent_diary-4.4.0}/setup.cfg +0 -0
  32. {agent_diary-4.3.0 → agent_diary-4.4.0}/skills/diary/SKILL.md +0 -0
  33. {agent_diary-4.3.0 → agent_diary-4.4.0}/skills/diary/agents/openai.yaml +0 -0
  34. {agent_diary-4.3.0 → agent_diary-4.4.0}/skills/diary-notion/agents/openai.yaml +0 -0
  35. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/agent_diary.egg-info/SOURCES.txt +0 -0
  36. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/agent_diary.egg-info/dependency_links.txt +0 -0
  37. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/agent_diary.egg-info/entry_points.txt +0 -0
  38. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/agent_diary.egg-info/top_level.txt +0 -0
  39. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/__main__.py +0 -0
  40. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/maintenance.py +0 -0
  41. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_common.py +0 -0
  42. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_ensure.py +0 -0
  43. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_init.py +0 -0
  44. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_ops.py +0 -0
  45. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_push/artifacts.py +0 -0
  46. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_push/preview.py +0 -0
  47. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_push/relations.py +0 -0
  48. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_push/tasks.py +0 -0
  49. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/notion_review.py +0 -0
  50. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/search.py +0 -0
  51. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/stats.py +0 -0
  52. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/cli/team.py +0 -0
  53. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/config.py +0 -0
  54. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/exporters/__init__.py +0 -0
  55. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/exporters/base.py +0 -0
  56. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/exporters/discord.py +0 -0
  57. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/exporters/github.py +0 -0
  58. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/exporters/loader.py +0 -0
  59. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/exporters/notion.py +0 -0
  60. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/exporters/notion_hierarchical.py +0 -0
  61. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/exporters/notion_views.py +0 -0
  62. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/exporters/obsidian.py +0 -0
  63. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/exporters/slack.py +0 -0
  64. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/hook.py +0 -0
  65. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/i18n.py +0 -0
  66. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/indexer.py +0 -0
  67. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/lib/__init__.py +0 -0
  68. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/lib/audit.py +0 -0
  69. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/lib/categorizer.py +0 -0
  70. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/lib/notion_cache.py +0 -0
  71. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/lib/parser.py +0 -0
  72. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/lib/stats.py +0 -0
  73. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/lib/team_security.py +0 -0
  74. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/log.py +0 -0
  75. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/team.py +0 -0
  76. {agent_diary-4.3.0 → agent_diary-4.4.0}/src/claude_diary/writer.py +0 -0
  77. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_audit.py +0 -0
  78. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_categorizer.py +0 -0
  79. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_codex_plugin.py +0 -0
  80. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_config.py +0 -0
  81. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_core.py +0 -0
  82. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_dashboard.py +0 -0
  83. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_exporters.py +0 -0
  84. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_formatter.py +0 -0
  85. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_git_info.py +0 -0
  86. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_hook.py +0 -0
  87. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_i18n.py +0 -0
  88. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_indexer.py +0 -0
  89. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_notion_cache.py +0 -0
  90. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_notion_ensure.py +0 -0
  91. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_notion_hierarchical.py +0 -0
  92. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_notion_init.py +0 -0
  93. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_notion_ops.py +0 -0
  94. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_notion_review.py +0 -0
  95. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_notion_views.py +0 -0
  96. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_parser.py +0 -0
  97. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_secret_scanner.py +0 -0
  98. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_setup.py +0 -0
  99. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_stats.py +0 -0
  100. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_team.py +0 -0
  101. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_team_security.py +0 -0
  102. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_write.py +0 -0
  103. {agent_diary-4.3.0 → agent_diary-4.4.0}/tests/test_writer.py +0 -0
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-diary",
3
- "version": "4.3.0",
3
+ "version": "4.4.0",
4
4
  "description": "Record AI coding sessions as Markdown diaries or task-based Notion entries.",
5
5
  "author": {
6
6
  "name": "solzip",
@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [4.4.0] - 2026-08-11
11
+
12
+ ### Added
13
+
14
+ - **[Architecture 문서](docs/ARCHITECTURE.md)**: 멱등성 키와 캐시 무효화, 원인별로 갈리는 재시도 정책, 스키마 버전 관리, 부분 실패의 의미, 의존성 0개를 택한 이유. 코드에 이미 있던 판단들이 README에서는 보이지 않던 것을 드러냄
15
+ - **[Postmortem: 2026-08-07 ensure 사고](docs/postmortem/2026-08-07-ensure-wipe.md)**: 스키마 PATCH 하나가 497 row에서 6개 속성을 지운 경위. 원인을 좁힌 측정(`Project`·`Branch`가 무사했던 것), 수정, 회귀 테스트를 그렇게 짠 이유, 아직 복구되지 않은 것까지
16
+ - **타입 검사**: `mypy`가 CI에서 주석 처리된 코어 모듈을 검사한다. `pyproject.toml`의 목록이 검사 범위이고, 저장소 전체에 켜고 나머지를 `ignore_errors`로 덮는 방식은 택하지 않았다
17
+
18
+ ### Changed
19
+
20
+ - **`types.py`가 주석이 아니라 실제 타입이 됨**: `EntryData`, `GitInfo`, `DiffStat`, `CommitInfo`, `Config` 등을 `TypedDict`로 정의. 기존 주석은 Python 3.7 호환을 이유로 들었지만 하한은 이미 3.8이었고, 그 사이 주석이 실제와 어긋나 있었다(커밋의 `short_hash` 누락, parser가 만드는 키 3개 누락). 주석은 실패할 수 없다는 게 문제였다
21
+ - 코어에 타입을 붙이자 **타입이 실제로는 흐르지 않던 6곳**이 드러났다. `entry_data`가 dict 리터럴로 만들어져서 `_supplement_from_git`·`scan_entry_data`·`format_entry`·`_run_exporters`가 전부 `dict[str, Any]`를 받고 있었다
22
+ - 시그니처만 변경. 함수 본문은 손대지 않아 동작 변화는 없다
23
+ - **`Schema Version`의 `vlegacy`를 우연이 아니라 의도로** ([#11](https://github.com/solzip/agent-diary/issues/11)): 값은 그대로 유지한다. 실측 결과 509 row 중 350개가 쓰는 실존 select 옵션이라, 다른 문자열을 쓰면 세 번째 옵션이 생기고 기존 row가 옛 옵션에 남는다. 이름 변경은 여기서 할 편집이 아니라 데이터베이스 마이그레이션이다. 이제 `LEGACY_SCHEMA_VERSION` 상수로 명시하고 테스트로 고정했다
24
+
25
+ ### Fixed
26
+
27
+ - **dry-run이 실제 push와 다른 제목을 보여주던 문제** ([#10](https://github.com/solzip/agent-diary/issues/10)): 미리보기가 자격증명 해석 **전에** 끝나서 차수 조회를 못 했고, 결과적으로 이어지는 task group인데도 `(N차)` 없이 렌더링됐다. 미리보기가 예측 대상과 어긋나는 상태였다
28
+ - 자격증명이 있으면 dry-run도 차수를 조회해 제목에 반영한다
29
+ - **`ensure_database`는 호출하지 않는다.** 이 함수는 없으면 연도 페이지와 데이터베이스를 *생성*하므로 미리보기가 불러선 안 된다. DB ID는 로컬 캐시에서만 읽고, 캐시가 없으면 조회를 포기한다
30
+ - 자격증명이 없거나 캐시가 비었거나 조회가 실패하면 제목을 건드리지 않고, 미리보기 상단에 "차수가 확정되지 않았다"고 밝힌다. `diary-notion init` 전에도 dry-run은 그대로 쓸 수 있다
31
+
32
+ ### Known
33
+
34
+ - 실제 push가 저장하는 `preview.md`는 차수 부여 **전에** 렌더링된다. `--force` archive 이후에 차수를 매겨야 하고, 미리보기는 네트워크 호출 전에 남겨야 push가 중간에 실패해도 기록이 보존되기 때문이다. 화면 출력과 Notion row는 정확하지만 저장된 `preview.md`의 제목에는 `(N차)`가 빠진다
35
+
36
+ ## [4.3.1] - 2026-08-11
37
+
38
+ ### Fixed
39
+
40
+ - **CLI가 스스로를 옛 이름으로 소개하던 문제**: `argparse`의 `prog`와 `--version` 문자열이 `claude-diary`로 하드코딩돼 있어서, `pip install agent-diary` 후 `agent-diary --version`을 실행하면 `claude-diary 4.3.0`이라고 답했다. `--help`의 usage 줄도 마찬가지
41
+ - 사용자 눈에 보이는 나머지 옛 이름 정리: `uninstall --codex` 도움말, `write`의 안내 출력, HTML 대시보드 footer
42
+ - Obsidian exporter의 `subfolder` 기본값(`claude-diary`)은 **유지**. 이건 이름이 아니라 사용자 vault 안의 경로라, 바꾸면 기존 노트가 두 폴더로 갈라진다
43
+
10
44
  ## [4.3.0] - 2026-08-11
11
45
 
12
46
  ### Changed — 이름
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agent-diary
3
- Version: 4.3.0
3
+ Version: 4.4.0
4
4
  Summary: Record Claude Code and Codex work sessions as Markdown or Notion work diaries
5
5
  Author: solzip
6
6
  License: MIT
@@ -29,6 +29,7 @@ Provides-Extra: dev
29
29
  Requires-Dist: pytest>=7.0; extra == "dev"
30
30
  Requires-Dist: pytest-cov>=4.0; extra == "dev"
31
31
  Requires-Dist: ruff>=0.4.0; extra == "dev"
32
+ Requires-Dist: mypy>=1.0; extra == "dev"
32
33
  Dynamic: license-file
33
34
 
34
35
  # Agent Diary
@@ -46,6 +47,8 @@ Dynamic: license-file
46
47
 
47
48
  ![Agent Diary demo](docs/demo.svg)
48
49
 
50
+ > **Here to read the code?** [Architecture](docs/ARCHITECTURE.md) covers the idempotency key and its cache invalidation, a retry policy that branches on cause, schema versioning, and what partial failure means. The [postmortem](docs/postmortem/2026-08-07-ensure-wipe.md) is how one schema PATCH emptied six properties across 497 rows.
51
+
49
52
  ## 1. Why
50
53
 
51
54
  Work done with an AI lives in a chat window, and chat windows close. Two days later there is no way back to why a file was changed the way it was, and when a weekly review or a status report comes due you are working from memory. A commit log keeps the result; it does not keep what you asked for or what was tried on the way there.
@@ -169,16 +172,16 @@ Claude Code plugin installation is a separate distribution path for Claude Code
169
172
  ```bash
170
173
  # Run inside Claude Code
171
174
  /plugin marketplace add https://github.com/solzip/agent-diary
172
- /plugin install working-diary
175
+ /plugin install agent-diary
173
176
  ```
174
177
 
175
- The plugin distributes Claude Code hook settings. The `working-diary` CLI comes from the Python package, so Python package installation and `agent-diary init` are still required.
178
+ The plugin distributes Claude Code hook settings. The `agent-diary` CLI comes from the Python package, so Python package installation and `agent-diary init` are still required.
176
179
 
177
180
  Install from source:
178
181
 
179
182
  ```bash
180
183
  git clone https://github.com/solzip/agent-diary.git
181
- cd working-diary
184
+ cd agent-diary
182
185
  pip install -e .
183
186
  agent-diary init
184
187
  ```
@@ -299,6 +302,7 @@ agent-diary diary-notion push --input .diary-notion-<id>.json --dry-run
299
302
  - `--force` archives prior rows for the session and pushes again.
300
303
  - `--dry-run` prints the rows and page bodies that would be created without writing to Notion. Add `--preview-file <path>` to save the same rendering as Markdown.
301
304
  - If a `Task Group` already has recorded sessions, the title gets an `(N차)` ordinal. The first session of a group is left alone.
305
+ - `--dry-run` **reads** from Notion to resolve that ordinal — a query, nothing more. Without credentials, or before that year's database exists, it renders without the ordinal and says so at the top of the output. A preview never creates a page or a database.
302
306
  - If any task fails, the command exits with code `1` and preserves the input JSON.
303
307
  - Fully successful pushes and already-skipped pushes exit with code `0`.
304
308
 
@@ -353,6 +357,8 @@ Rows are still recorded if Sub-items are not enabled. Only visual nesting is mis
353
357
 
354
358
  ## 3. Logic
355
359
 
360
+ This section covers **what flows where, in what order**. Why it is built that way — the idempotency key, the retry policy, schema versioning, partial-failure handling — is in [Architecture](docs/ARCHITECTURE.md).
361
+
356
362
  ### 3-1. Core Logic
357
363
 
358
364
  The core handles actual recording independently of the agent.
@@ -520,15 +526,21 @@ agent-diary diary-notion ensure
520
526
 
521
527
  The config file is stored at the OS-specific user config path under `claude-diary/config.json`. If you configure exporters such as Notion, Slack, or Discord, API tokens, webhook URLs, and root page IDs are stored in this local config. CLI output masks long token and webhook values.
522
528
 
523
- | Environment variable | Description | Default |
524
- |----------------------|-------------|---------|
525
- | `CLAUDE_DIARY_LANG` | Diary language, `ko` or `en` | `ko` |
526
- | `CLAUDE_DIARY_DIR` | Automatic diary path | `~/working-diary` |
527
- | `CLAUDE_DIARY_MANUAL_DIR` | Manual diary path | `~/working-diary/manual` |
528
- | `CLAUDE_DIARY_TZ_OFFSET` | UTC offset | `9` |
529
- | `CLAUDE_DIARY_NOTION_TOKEN` | Notion token, overrides config | - |
530
- | `CLAUDE_DIARY_NOTION_ROOT_PAGE_ID` | Notion root page ID, overrides config | - |
531
- | `CLAUDE_DIARY_SKIP` | `1`, `true`, or `yes` skips Claude Code Stop Hook auto diary | - |
529
+ These variables fall into **two groups whose precedence runs in opposite directions**. Read the last column first.
530
+
531
+ | Environment variable | Description | Default | Precedence |
532
+ |----------------------|-------------|---------|------------|
533
+ | `CLAUDE_DIARY_LANG` | Diary language, `ko` or `en` | `ko` | config.json wins |
534
+ | `CLAUDE_DIARY_DIR` | Automatic diary path | `~/working-diary` | config.json wins |
535
+ | `CLAUDE_DIARY_MANUAL_DIR` | Manual diary path | `~/working-diary/manual` | config.json wins |
536
+ | `CLAUDE_DIARY_TZ_OFFSET` | UTC offset | `9` | config.json wins |
537
+ | `CLAUDE_DIARY_NOTION_TOKEN` | Notion token | - | **env wins** |
538
+ | `CLAUDE_DIARY_NOTION_ROOT_PAGE_ID` | Notion root page ID | - | **env wins** |
539
+ | `CLAUDE_DIARY_SKIP` | `1`, `true`, or `yes` skips Claude Code Stop Hook auto diary | - | env only |
540
+
541
+ The first four merge as `config.json > environment > defaults`. So if you have ever run `init`, the key is already written to the config and **setting the environment variable has no effect.** To move the diary path, edit `config.json` rather than exporting a variable.
542
+
543
+ The two Notion credentials are the exception and override the config, so a token need not be written to a file in CI or when moving between workspaces.
532
544
 
533
545
  If PowerShell output shows broken Korean or emoji characters, switch the current session output encoding to UTF-8.
534
546
 
@@ -573,8 +585,13 @@ $OutputEncoding = [System.Text.UTF8Encoding]::new()
573
585
  pip install -e ".[dev,notion]"
574
586
  python -m pytest -q
575
587
  python -m ruff check .
588
+ python -m mypy
576
589
  ```
577
590
 
591
+ Run bare, `mypy` checks only the modules listed in `pyproject.toml`. That list is the annotated core, and CI keeps it green. Annotating a new module means adding it to the list — being on the list is a commitment to stay clean.
592
+
593
+ CI runs it on the Python 3.12 job only, because current mypy will not run under this project's 3.8 floor. The annotations themselves are written for 3.8.
594
+
578
595
  ## 9. Roadmap
579
596
 
580
597
  This README focuses on currently usable functionality. Detailed design and planning artifacts live under `docs/`.
@@ -588,6 +605,13 @@ This README focuses on currently usable functionality. Detailed design and plann
588
605
 
589
606
  ## 10. Documentation
590
607
 
608
+ If you are deciding whether the code is worth reading, start with these two.
609
+
610
+ - **[Architecture](docs/ARCHITECTURE.md)** — the idempotency model, the retry and error-taxonomy policy, cache invalidation, schema versioning, what partial failure means, and why the core has no dependencies
611
+ - **[Postmortem: `ensure` emptied six properties across 497 rows](docs/postmortem/2026-08-07-ensure-wipe.md)** — symptom, measurement against production, root cause, fix, regression tests, and why it went unseen for two months
612
+
613
+ Detailed design notes:
614
+
591
615
  - [Notion hierarchical design](docs/02-design/features/diary-notion-hierarchical.design.md)
592
616
  - [Notion views design](docs/02-design/features/diary-notion-views.design.md)
593
617
  - [Distribution plan](docs/plans/phase-d-distribution.md)
@@ -13,6 +13,8 @@
13
13
 
14
14
  ![Agent Diary demo](docs/demo.svg)
15
15
 
16
+ > **Here to read the code?** [Architecture](docs/ARCHITECTURE.md) covers the idempotency key and its cache invalidation, a retry policy that branches on cause, schema versioning, and what partial failure means. The [postmortem](docs/postmortem/2026-08-07-ensure-wipe.md) is how one schema PATCH emptied six properties across 497 rows.
17
+
16
18
  ## 1. Why
17
19
 
18
20
  Work done with an AI lives in a chat window, and chat windows close. Two days later there is no way back to why a file was changed the way it was, and when a weekly review or a status report comes due you are working from memory. A commit log keeps the result; it does not keep what you asked for or what was tried on the way there.
@@ -136,16 +138,16 @@ Claude Code plugin installation is a separate distribution path for Claude Code
136
138
  ```bash
137
139
  # Run inside Claude Code
138
140
  /plugin marketplace add https://github.com/solzip/agent-diary
139
- /plugin install working-diary
141
+ /plugin install agent-diary
140
142
  ```
141
143
 
142
- The plugin distributes Claude Code hook settings. The `working-diary` CLI comes from the Python package, so Python package installation and `agent-diary init` are still required.
144
+ The plugin distributes Claude Code hook settings. The `agent-diary` CLI comes from the Python package, so Python package installation and `agent-diary init` are still required.
143
145
 
144
146
  Install from source:
145
147
 
146
148
  ```bash
147
149
  git clone https://github.com/solzip/agent-diary.git
148
- cd working-diary
150
+ cd agent-diary
149
151
  pip install -e .
150
152
  agent-diary init
151
153
  ```
@@ -266,6 +268,7 @@ agent-diary diary-notion push --input .diary-notion-<id>.json --dry-run
266
268
  - `--force` archives prior rows for the session and pushes again.
267
269
  - `--dry-run` prints the rows and page bodies that would be created without writing to Notion. Add `--preview-file <path>` to save the same rendering as Markdown.
268
270
  - If a `Task Group` already has recorded sessions, the title gets an `(N차)` ordinal. The first session of a group is left alone.
271
+ - `--dry-run` **reads** from Notion to resolve that ordinal — a query, nothing more. Without credentials, or before that year's database exists, it renders without the ordinal and says so at the top of the output. A preview never creates a page or a database.
269
272
  - If any task fails, the command exits with code `1` and preserves the input JSON.
270
273
  - Fully successful pushes and already-skipped pushes exit with code `0`.
271
274
 
@@ -320,6 +323,8 @@ Rows are still recorded if Sub-items are not enabled. Only visual nesting is mis
320
323
 
321
324
  ## 3. Logic
322
325
 
326
+ This section covers **what flows where, in what order**. Why it is built that way — the idempotency key, the retry policy, schema versioning, partial-failure handling — is in [Architecture](docs/ARCHITECTURE.md).
327
+
323
328
  ### 3-1. Core Logic
324
329
 
325
330
  The core handles actual recording independently of the agent.
@@ -487,15 +492,21 @@ agent-diary diary-notion ensure
487
492
 
488
493
  The config file is stored at the OS-specific user config path under `claude-diary/config.json`. If you configure exporters such as Notion, Slack, or Discord, API tokens, webhook URLs, and root page IDs are stored in this local config. CLI output masks long token and webhook values.
489
494
 
490
- | Environment variable | Description | Default |
491
- |----------------------|-------------|---------|
492
- | `CLAUDE_DIARY_LANG` | Diary language, `ko` or `en` | `ko` |
493
- | `CLAUDE_DIARY_DIR` | Automatic diary path | `~/working-diary` |
494
- | `CLAUDE_DIARY_MANUAL_DIR` | Manual diary path | `~/working-diary/manual` |
495
- | `CLAUDE_DIARY_TZ_OFFSET` | UTC offset | `9` |
496
- | `CLAUDE_DIARY_NOTION_TOKEN` | Notion token, overrides config | - |
497
- | `CLAUDE_DIARY_NOTION_ROOT_PAGE_ID` | Notion root page ID, overrides config | - |
498
- | `CLAUDE_DIARY_SKIP` | `1`, `true`, or `yes` skips Claude Code Stop Hook auto diary | - |
495
+ These variables fall into **two groups whose precedence runs in opposite directions**. Read the last column first.
496
+
497
+ | Environment variable | Description | Default | Precedence |
498
+ |----------------------|-------------|---------|------------|
499
+ | `CLAUDE_DIARY_LANG` | Diary language, `ko` or `en` | `ko` | config.json wins |
500
+ | `CLAUDE_DIARY_DIR` | Automatic diary path | `~/working-diary` | config.json wins |
501
+ | `CLAUDE_DIARY_MANUAL_DIR` | Manual diary path | `~/working-diary/manual` | config.json wins |
502
+ | `CLAUDE_DIARY_TZ_OFFSET` | UTC offset | `9` | config.json wins |
503
+ | `CLAUDE_DIARY_NOTION_TOKEN` | Notion token | - | **env wins** |
504
+ | `CLAUDE_DIARY_NOTION_ROOT_PAGE_ID` | Notion root page ID | - | **env wins** |
505
+ | `CLAUDE_DIARY_SKIP` | `1`, `true`, or `yes` skips Claude Code Stop Hook auto diary | - | env only |
506
+
507
+ The first four merge as `config.json > environment > defaults`. So if you have ever run `init`, the key is already written to the config and **setting the environment variable has no effect.** To move the diary path, edit `config.json` rather than exporting a variable.
508
+
509
+ The two Notion credentials are the exception and override the config, so a token need not be written to a file in CI or when moving between workspaces.
499
510
 
500
511
  If PowerShell output shows broken Korean or emoji characters, switch the current session output encoding to UTF-8.
501
512
 
@@ -540,8 +551,13 @@ $OutputEncoding = [System.Text.UTF8Encoding]::new()
540
551
  pip install -e ".[dev,notion]"
541
552
  python -m pytest -q
542
553
  python -m ruff check .
554
+ python -m mypy
543
555
  ```
544
556
 
557
+ Run bare, `mypy` checks only the modules listed in `pyproject.toml`. That list is the annotated core, and CI keeps it green. Annotating a new module means adding it to the list — being on the list is a commitment to stay clean.
558
+
559
+ CI runs it on the Python 3.12 job only, because current mypy will not run under this project's 3.8 floor. The annotations themselves are written for 3.8.
560
+
545
561
  ## 9. Roadmap
546
562
 
547
563
  This README focuses on currently usable functionality. Detailed design and planning artifacts live under `docs/`.
@@ -555,6 +571,13 @@ This README focuses on currently usable functionality. Detailed design and plann
555
571
 
556
572
  ## 10. Documentation
557
573
 
574
+ If you are deciding whether the code is worth reading, start with these two.
575
+
576
+ - **[Architecture](docs/ARCHITECTURE.md)** — the idempotency model, the retry and error-taxonomy policy, cache invalidation, schema versioning, what partial failure means, and why the core has no dependencies
577
+ - **[Postmortem: `ensure` emptied six properties across 497 rows](docs/postmortem/2026-08-07-ensure-wipe.md)** — symptom, measurement against production, root cause, fix, regression tests, and why it went unseen for two months
578
+
579
+ Detailed design notes:
580
+
558
581
  - [Notion hierarchical design](docs/02-design/features/diary-notion-hierarchical.design.md)
559
582
  - [Notion views design](docs/02-design/features/diary-notion-views.design.md)
560
583
  - [Distribution plan](docs/plans/phase-d-distribution.md)
@@ -13,6 +13,8 @@
13
13
 
14
14
  ![Agent Diary 데모](docs/demo.svg)
15
15
 
16
+ > **코드를 보러 오셨다면** — [Architecture](docs/ARCHITECTURE.md)에 멱등성 키와 캐시 무효화, 원인별로 갈리는 재시도 정책, 스키마 버전 관리, 부분 실패의 의미를 정리해뒀습니다. [Postmortem](docs/postmortem/2026-08-07-ensure-wipe.md)은 스키마 PATCH 하나가 497 row에서 6개 속성을 지운 사고의 전말입니다.
17
+
16
18
  ## 1. 왜 필요한가
17
19
 
18
20
  AI와 한 작업은 대화창에 남고, 대화창은 닫힙니다. 이틀 뒤 "이 파일 왜 이렇게 고쳤더라"를 되짚을 방법이 없고, 주간 회고나 업무일지를 쓸 때가 되면 기억에 의존하게 됩니다. 커밋 로그는 결과만 남기지 무엇을 요청했고 무엇을 시도했는지는 남기지 않습니다.
@@ -136,16 +138,16 @@ Claude Code 플러그인 설치는 별도 배포 경로입니다. Claude Code의
136
138
  ```bash
137
139
  # Claude Code 안에서 실행
138
140
  /plugin marketplace add https://github.com/solzip/agent-diary
139
- /plugin install working-diary
141
+ /plugin install agent-diary
140
142
  ```
141
143
 
142
- 이 플러그인은 Claude Code 쪽 hook 설정을 배포합니다. `working-diary` CLI는 Python 패키지에서 제공되므로, 플러그인 경로를 쓰더라도 Python 패키지 설치와 `agent-diary init`이 준비되어 있어야 합니다.
144
+ 이 플러그인은 Claude Code 쪽 hook 설정을 배포합니다. `agent-diary` CLI는 Python 패키지에서 제공되므로, 플러그인 경로를 쓰더라도 Python 패키지 설치와 `agent-diary init`이 준비되어 있어야 합니다.
143
145
 
144
146
  소스에서 설치:
145
147
 
146
148
  ```bash
147
149
  git clone https://github.com/solzip/agent-diary.git
148
- cd working-diary
150
+ cd agent-diary
149
151
  pip install -e .
150
152
  agent-diary init
151
153
  ```
@@ -268,6 +270,7 @@ agent-diary diary-notion push --input .diary-notion-<id>.json --dry-run
268
270
  - `--force`는 같은 세션의 기존 row를 archive한 뒤 다시 push합니다.
269
271
  - `--dry-run`은 Notion에 쓰지 않고 만들어질 row와 page 본문을 출력합니다. `--preview-file <path>`를 함께 주면 같은 내용을 Markdown 파일로 저장합니다.
270
272
  - 같은 `Task Group`에 이미 기록된 세션이 있으면 제목에 `(N차)`가 붙습니다. 첫 세션에는 붙지 않습니다.
273
+ - `--dry-run`도 차수를 반영하려고 Notion을 **읽습니다**(조회만). 자격증명이 없거나 아직 해당 연도 DB를 만든 적이 없으면 차수 없이 렌더링하고 그 사실을 출력 상단에 밝힙니다. 미리보기가 데이터베이스나 페이지를 새로 만드는 일은 없습니다.
271
274
  - 실패한 task가 하나라도 있으면 exit code `1`로 종료하고 입력 JSON을 보존합니다.
272
275
  - 전체 성공 또는 이미 push된 task만 skip된 경우 exit code `0`으로 종료합니다.
273
276
 
@@ -322,6 +325,8 @@ Sub-items가 아직 없어도 row 기록은 정상 동작합니다. 다만 계
322
325
 
323
326
  ## 3. 로직
324
327
 
328
+ 이 절은 **무엇이 어떤 순서로 흐르는가**를 다룹니다. 왜 그렇게 설계했는지 — 멱등성 키, 재시도 정책, 스키마 버전 관리, 부분 실패 처리 — 는 [Architecture](docs/ARCHITECTURE.md)에 있습니다.
329
+
325
330
  ### 3-1. Core 로직
326
331
 
327
332
  Core는 에이전트와 무관하게 실제 기록 처리를 담당합니다.
@@ -491,15 +496,21 @@ agent-diary diary-notion ensure
491
496
 
492
497
  설정 파일은 OS별 사용자 config 경로의 `claude-diary/config.json`에 저장됩니다. Notion 같은 exporter를 설정하면 API token, webhook URL, root page ID도 이 로컬 config에 저장됩니다. CLI 출력에서는 긴 token과 webhook 값을 masking해서 보여줍니다.
493
498
 
494
- | 환경변수 | 설명 | 기본값 |
495
- |----------|------|--------|
496
- | `CLAUDE_DIARY_LANG` | 일지 언어. `ko` 또는 `en` | `ko` |
497
- | `CLAUDE_DIARY_DIR` | 자동 일지 저장 경로 | `~/working-diary` |
498
- | `CLAUDE_DIARY_MANUAL_DIR` | 수동 일지 저장 경로 | `~/working-diary/manual` |
499
- | `CLAUDE_DIARY_TZ_OFFSET` | UTC offset | `9` |
500
- | `CLAUDE_DIARY_NOTION_TOKEN` | Notion token. config보다 우선 | - |
501
- | `CLAUDE_DIARY_NOTION_ROOT_PAGE_ID` | Notion root page ID. config보다 우선 | - |
502
- | `CLAUDE_DIARY_SKIP` | `1`, `true`, `yes`이면 Claude Code Stop Hook 자동 기록 skip | - |
499
+ 환경변수는 **두 부류로 우선순위가 반대**입니다. 아래 표의 "우선순위" 열을 먼저 보세요.
500
+
501
+ | 환경변수 | 설명 | 기본값 | 우선순위 |
502
+ |----------|------|--------|----------|
503
+ | `CLAUDE_DIARY_LANG` | 일지 언어. `ko` 또는 `en` | `ko` | config.json이 이김 |
504
+ | `CLAUDE_DIARY_DIR` | 자동 일지 저장 경로 | `~/working-diary` | config.json이 이김 |
505
+ | `CLAUDE_DIARY_MANUAL_DIR` | 수동 일지 저장 경로 | `~/working-diary/manual` | config.json이 이김 |
506
+ | `CLAUDE_DIARY_TZ_OFFSET` | UTC offset | `9` | config.json이 이김 |
507
+ | `CLAUDE_DIARY_NOTION_TOKEN` | Notion token | - | **환경변수가 이김** |
508
+ | `CLAUDE_DIARY_NOTION_ROOT_PAGE_ID` | Notion root page ID | - | **환경변수가 이김** |
509
+ | `CLAUDE_DIARY_SKIP` | `1`, `true`, `yes`이면 Claude Code Stop Hook 자동 기록 skip | - | 환경변수 전용 |
510
+
511
+ 앞의 네 개는 `config.json > 환경변수 > 기본값` 순서로 병합됩니다. 즉 `init`을 한 번이라도 실행했다면 해당 키가 config에 기록돼 있어서 **환경변수를 지정해도 무시됩니다.** 저장 경로를 임시로 바꾸려면 환경변수가 아니라 `config.json`을 고쳐야 합니다.
512
+
513
+ Notion 자격증명 두 개만 반대로, 환경변수가 config를 덮어씁니다. CI나 여러 워크스페이스를 오갈 때 토큰을 파일에 남기지 않기 위한 예외입니다.
503
514
 
504
515
  PowerShell에서 한글이나 이모지가 깨져 보이면 현재 세션 출력 인코딩을 UTF-8로 바꿉니다.
505
516
 
@@ -544,8 +555,13 @@ $OutputEncoding = [System.Text.UTF8Encoding]::new()
544
555
  pip install -e ".[dev,notion]"
545
556
  python -m pytest -q
546
557
  python -m ruff check .
558
+ python -m mypy
547
559
  ```
548
560
 
561
+ `mypy`는 인자 없이 실행하면 `pyproject.toml`에 나열된 모듈만 검사합니다. 타입을 붙인 코어가 그 목록이고, CI가 초록으로 유지합니다. 모듈을 새로 주석 처리하면 목록에 추가하세요 — 목록에 올린다는 건 앞으로 계속 통과시키겠다는 약속입니다.
562
+
563
+ CI에서는 Python 3.12 작업에서만 돕니다. 현재 mypy가 이 프로젝트의 하한인 3.8에서 실행되지 않기 때문이고, 어노테이션 자체는 3.8 기준으로 작성돼 있습니다.
564
+
549
565
  ## 9. 로드맵
550
566
 
551
567
  현재 README는 사용 가능한 기능을 중심으로 유지하고, 상세 설계와 진행 기록은 `docs/`에 둡니다.
@@ -559,6 +575,13 @@ python -m ruff check .
559
575
 
560
576
  ## 10. 문서
561
577
 
578
+ 코드를 읽을지 판단하려는 분이라면 이 둘을 먼저 보세요.
579
+
580
+ - **[Architecture](docs/ARCHITECTURE.md)** — 멱등성 모델, 재시도·에러 분류 정책, 캐시 무효화, 스키마 버전 관리, 부분 실패의 의미, 의존성 0개를 택한 이유
581
+ - **[Postmortem: `ensure`가 497 row의 6개 속성을 지운 사고](docs/postmortem/2026-08-07-ensure-wipe.md)** — 증상, 프로덕션 대조 측정, 근본 원인, 수정, 회귀 테스트, 그리고 두 달간 못 본 이유
582
+
583
+ 세부 설계 문서:
584
+
562
585
  - [Notion hierarchical design](docs/02-design/features/diary-notion-hierarchical.design.md)
563
586
  - [Notion views design](docs/02-design/features/diary-notion-views.design.md)
564
587
  - [Distribution plan](docs/plans/phase-d-distribution.md)
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "agent-diary"
7
- version = "4.3.0"
7
+ version = "4.4.0"
8
8
  description = "Record Claude Code and Codex work sessions as Markdown or Notion work diaries"
9
9
  readme = "README.en.md"
10
10
  license = {text = "MIT"}
@@ -29,7 +29,7 @@ dependencies = []
29
29
  [project.optional-dependencies]
30
30
  notion = ["requests>=2.28"]
31
31
  all = ["requests>=2.28"]
32
- dev = ["pytest>=7.0", "pytest-cov>=4.0", "ruff>=0.4.0"]
32
+ dev = ["pytest>=7.0", "pytest-cov>=4.0", "ruff>=0.4.0", "mypy>=1.0"]
33
33
 
34
34
  [project.scripts]
35
35
  # The import package stays `claude_diary`: `python -m claude_diary.hook` is
@@ -51,6 +51,21 @@ where = ["src"]
51
51
  testpaths = ["tests"]
52
52
  pythonpath = ["src"]
53
53
 
54
+ [tool.mypy]
55
+ # The annotated core, not the whole codebase. Everything listed here is clean
56
+ # and CI keeps it that way; adding a module to this list is a commitment, so
57
+ # the list grows as modules are annotated rather than all at once with
58
+ # `ignore_errors` hiding the gap.
59
+ files = [
60
+ "src/claude_diary/types.py",
61
+ "src/claude_diary/core.py",
62
+ "src/claude_diary/formatter.py",
63
+ "src/claude_diary/lib/git_info.py",
64
+ "src/claude_diary/lib/secret_scanner.py",
65
+ "src/claude_diary/cli/notion_push/properties.py",
66
+ ]
67
+ ignore_missing_imports = true
68
+
54
69
  [tool.ruff]
55
70
  target-version = "py38"
56
71
  line-length = 120
@@ -141,7 +141,7 @@ Split the current Codex session into task-sized entries and push them to Notion.
141
141
  "blocked": false,
142
142
  "block_reason": "",
143
143
  "carryover": false,
144
- "task_group": "working-diary-notion",
144
+ "task_group": "agent-diary-notion",
145
145
  "parent_index": null,
146
146
  "depends_on_indices": [],
147
147
  "categories": ["feature"],
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agent-diary
3
- Version: 4.3.0
3
+ Version: 4.4.0
4
4
  Summary: Record Claude Code and Codex work sessions as Markdown or Notion work diaries
5
5
  Author: solzip
6
6
  License: MIT
@@ -29,6 +29,7 @@ Provides-Extra: dev
29
29
  Requires-Dist: pytest>=7.0; extra == "dev"
30
30
  Requires-Dist: pytest-cov>=4.0; extra == "dev"
31
31
  Requires-Dist: ruff>=0.4.0; extra == "dev"
32
+ Requires-Dist: mypy>=1.0; extra == "dev"
32
33
  Dynamic: license-file
33
34
 
34
35
  # Agent Diary
@@ -46,6 +47,8 @@ Dynamic: license-file
46
47
 
47
48
  ![Agent Diary demo](docs/demo.svg)
48
49
 
50
+ > **Here to read the code?** [Architecture](docs/ARCHITECTURE.md) covers the idempotency key and its cache invalidation, a retry policy that branches on cause, schema versioning, and what partial failure means. The [postmortem](docs/postmortem/2026-08-07-ensure-wipe.md) is how one schema PATCH emptied six properties across 497 rows.
51
+
49
52
  ## 1. Why
50
53
 
51
54
  Work done with an AI lives in a chat window, and chat windows close. Two days later there is no way back to why a file was changed the way it was, and when a weekly review or a status report comes due you are working from memory. A commit log keeps the result; it does not keep what you asked for or what was tried on the way there.
@@ -169,16 +172,16 @@ Claude Code plugin installation is a separate distribution path for Claude Code
169
172
  ```bash
170
173
  # Run inside Claude Code
171
174
  /plugin marketplace add https://github.com/solzip/agent-diary
172
- /plugin install working-diary
175
+ /plugin install agent-diary
173
176
  ```
174
177
 
175
- The plugin distributes Claude Code hook settings. The `working-diary` CLI comes from the Python package, so Python package installation and `agent-diary init` are still required.
178
+ The plugin distributes Claude Code hook settings. The `agent-diary` CLI comes from the Python package, so Python package installation and `agent-diary init` are still required.
176
179
 
177
180
  Install from source:
178
181
 
179
182
  ```bash
180
183
  git clone https://github.com/solzip/agent-diary.git
181
- cd working-diary
184
+ cd agent-diary
182
185
  pip install -e .
183
186
  agent-diary init
184
187
  ```
@@ -299,6 +302,7 @@ agent-diary diary-notion push --input .diary-notion-<id>.json --dry-run
299
302
  - `--force` archives prior rows for the session and pushes again.
300
303
  - `--dry-run` prints the rows and page bodies that would be created without writing to Notion. Add `--preview-file <path>` to save the same rendering as Markdown.
301
304
  - If a `Task Group` already has recorded sessions, the title gets an `(N차)` ordinal. The first session of a group is left alone.
305
+ - `--dry-run` **reads** from Notion to resolve that ordinal — a query, nothing more. Without credentials, or before that year's database exists, it renders without the ordinal and says so at the top of the output. A preview never creates a page or a database.
302
306
  - If any task fails, the command exits with code `1` and preserves the input JSON.
303
307
  - Fully successful pushes and already-skipped pushes exit with code `0`.
304
308
 
@@ -353,6 +357,8 @@ Rows are still recorded if Sub-items are not enabled. Only visual nesting is mis
353
357
 
354
358
  ## 3. Logic
355
359
 
360
+ This section covers **what flows where, in what order**. Why it is built that way — the idempotency key, the retry policy, schema versioning, partial-failure handling — is in [Architecture](docs/ARCHITECTURE.md).
361
+
356
362
  ### 3-1. Core Logic
357
363
 
358
364
  The core handles actual recording independently of the agent.
@@ -520,15 +526,21 @@ agent-diary diary-notion ensure
520
526
 
521
527
  The config file is stored at the OS-specific user config path under `claude-diary/config.json`. If you configure exporters such as Notion, Slack, or Discord, API tokens, webhook URLs, and root page IDs are stored in this local config. CLI output masks long token and webhook values.
522
528
 
523
- | Environment variable | Description | Default |
524
- |----------------------|-------------|---------|
525
- | `CLAUDE_DIARY_LANG` | Diary language, `ko` or `en` | `ko` |
526
- | `CLAUDE_DIARY_DIR` | Automatic diary path | `~/working-diary` |
527
- | `CLAUDE_DIARY_MANUAL_DIR` | Manual diary path | `~/working-diary/manual` |
528
- | `CLAUDE_DIARY_TZ_OFFSET` | UTC offset | `9` |
529
- | `CLAUDE_DIARY_NOTION_TOKEN` | Notion token, overrides config | - |
530
- | `CLAUDE_DIARY_NOTION_ROOT_PAGE_ID` | Notion root page ID, overrides config | - |
531
- | `CLAUDE_DIARY_SKIP` | `1`, `true`, or `yes` skips Claude Code Stop Hook auto diary | - |
529
+ These variables fall into **two groups whose precedence runs in opposite directions**. Read the last column first.
530
+
531
+ | Environment variable | Description | Default | Precedence |
532
+ |----------------------|-------------|---------|------------|
533
+ | `CLAUDE_DIARY_LANG` | Diary language, `ko` or `en` | `ko` | config.json wins |
534
+ | `CLAUDE_DIARY_DIR` | Automatic diary path | `~/working-diary` | config.json wins |
535
+ | `CLAUDE_DIARY_MANUAL_DIR` | Manual diary path | `~/working-diary/manual` | config.json wins |
536
+ | `CLAUDE_DIARY_TZ_OFFSET` | UTC offset | `9` | config.json wins |
537
+ | `CLAUDE_DIARY_NOTION_TOKEN` | Notion token | - | **env wins** |
538
+ | `CLAUDE_DIARY_NOTION_ROOT_PAGE_ID` | Notion root page ID | - | **env wins** |
539
+ | `CLAUDE_DIARY_SKIP` | `1`, `true`, or `yes` skips Claude Code Stop Hook auto diary | - | env only |
540
+
541
+ The first four merge as `config.json > environment > defaults`. So if you have ever run `init`, the key is already written to the config and **setting the environment variable has no effect.** To move the diary path, edit `config.json` rather than exporting a variable.
542
+
543
+ The two Notion credentials are the exception and override the config, so a token need not be written to a file in CI or when moving between workspaces.
532
544
 
533
545
  If PowerShell output shows broken Korean or emoji characters, switch the current session output encoding to UTF-8.
534
546
 
@@ -573,8 +585,13 @@ $OutputEncoding = [System.Text.UTF8Encoding]::new()
573
585
  pip install -e ".[dev,notion]"
574
586
  python -m pytest -q
575
587
  python -m ruff check .
588
+ python -m mypy
576
589
  ```
577
590
 
591
+ Run bare, `mypy` checks only the modules listed in `pyproject.toml`. That list is the annotated core, and CI keeps it green. Annotating a new module means adding it to the list — being on the list is a commitment to stay clean.
592
+
593
+ CI runs it on the Python 3.12 job only, because current mypy will not run under this project's 3.8 floor. The annotations themselves are written for 3.8.
594
+
578
595
  ## 9. Roadmap
579
596
 
580
597
  This README focuses on currently usable functionality. Detailed design and planning artifacts live under `docs/`.
@@ -588,6 +605,13 @@ This README focuses on currently usable functionality. Detailed design and plann
588
605
 
589
606
  ## 10. Documentation
590
607
 
608
+ If you are deciding whether the code is worth reading, start with these two.
609
+
610
+ - **[Architecture](docs/ARCHITECTURE.md)** — the idempotency model, the retry and error-taxonomy policy, cache invalidation, schema versioning, what partial failure means, and why the core has no dependencies
611
+ - **[Postmortem: `ensure` emptied six properties across 497 rows](docs/postmortem/2026-08-07-ensure-wipe.md)** — symptom, measurement against production, root cause, fix, regression tests, and why it went unseen for two months
612
+
613
+ Detailed design notes:
614
+
591
615
  - [Notion hierarchical design](docs/02-design/features/diary-notion-hierarchical.design.md)
592
616
  - [Notion views design](docs/02-design/features/diary-notion-views.design.md)
593
617
  - [Distribution plan](docs/plans/phase-d-distribution.md)
@@ -6,6 +6,7 @@ requests>=2.28
6
6
  pytest>=7.0
7
7
  pytest-cov>=4.0
8
8
  ruff>=0.4.0
9
+ mypy>=1.0
9
10
 
10
11
  [notion]
11
12
  requests>=2.28
@@ -1,3 +1,3 @@
1
1
  """Claude Code Working Diary — Auto-generate work diaries from Claude Code sessions."""
2
2
 
3
- __version__ = "4.3.0"
3
+ __version__ = "4.4.0"
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env python
2
- """claude-diary CLI — search, filter, stats, and manage your work diary."""
2
+ """agent-diary CLI — search, filter, stats, and manage your work diary."""
3
3
 
4
4
  import argparse
5
5
  import sys
@@ -67,11 +67,11 @@ def _add_diary_notion_parser(sub, name):
67
67
 
68
68
  def main():
69
69
  parser = argparse.ArgumentParser(
70
- prog="claude-diary",
71
- description="Auto-generated work diary from Claude Code sessions",
70
+ prog="agent-diary",
71
+ description="Auto-generated work diary from Claude Code and Codex sessions",
72
72
  )
73
73
  from claude_diary import __version__
74
- parser.add_argument("--version", action="version", version="claude-diary %s" % __version__)
74
+ parser.add_argument("--version", action="version", version="agent-diary %s" % __version__)
75
75
 
76
76
  sub = parser.add_subparsers(dest="command")
77
77
 
@@ -165,7 +165,7 @@ def main():
165
165
  p_uninstall = sub.add_parser("uninstall", help="Remove agent-diary hook from Claude Code")
166
166
  uninstall_agent = p_uninstall.add_mutually_exclusive_group()
167
167
  uninstall_agent.add_argument("--codex", action="store_true",
168
- help="Also remove Codex skills installed by claude-diary")
168
+ help="Also remove Codex skills installed by agent-diary")
169
169
  uninstall_agent.add_argument("--codex-only", action="store_true",
170
170
  help="Remove only Codex skills; do not modify Claude Code settings")
171
171
 
@@ -106,12 +106,12 @@ def cmd_init(args):
106
106
  # Team mode init
107
107
  if hasattr(args, 'team_repo') and args.team_repo:
108
108
  from claude_diary.team import init_team
109
- print("Initializing claude-diary (team mode)...")
109
+ print("Initializing agent-diary (team mode)...")
110
110
  print()
111
111
  init_team(args.team_repo)
112
112
  return
113
113
 
114
- print("Initializing claude-diary...")
114
+ print("Initializing agent-diary...")
115
115
  print()
116
116
 
117
117
  # Create diary directory