lifeos 1.0.2 → 1.1.0

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 (51) hide show
  1. package/README.md +20 -14
  2. package/README.zh.md +16 -11
  3. package/assets/lifeos-rules.en.md +1 -1
  4. package/assets/lifeos-rules.zh.md +1 -1
  5. package/assets/lifeos.yaml +1 -0
  6. package/assets/skills/archive/SKILL.en.md +1 -1
  7. package/assets/skills/archive/SKILL.zh.md +1 -1
  8. package/assets/skills/ask/SKILL.en.md +1 -1
  9. package/assets/skills/ask/SKILL.zh.md +1 -1
  10. package/assets/skills/brainstorm/SKILL.en.md +1 -1
  11. package/assets/skills/brainstorm/SKILL.zh.md +1 -1
  12. package/assets/skills/digest/SKILL.en.md +212 -0
  13. package/assets/skills/digest/SKILL.zh.md +207 -0
  14. package/assets/skills/digest/references/__pycache__/rss-arxiv-script.cpython-312.pyc +0 -0
  15. package/assets/skills/digest/references/config-parser.en.md +179 -0
  16. package/assets/skills/digest/references/config-parser.zh.md +177 -0
  17. package/assets/skills/digest/references/rss-arxiv-script.py +1549 -0
  18. package/assets/skills/digest/references/run-pipeline.en.md +236 -0
  19. package/assets/skills/digest/references/run-pipeline.zh.md +235 -0
  20. package/assets/skills/digest/references/setup-guide.en.md +192 -0
  21. package/assets/skills/digest/references/setup-guide.zh.md +188 -0
  22. package/assets/skills/knowledge/SKILL.en.md +1 -1
  23. package/assets/skills/knowledge/SKILL.zh.md +1 -1
  24. package/assets/skills/project/SKILL.en.md +1 -1
  25. package/assets/skills/project/SKILL.zh.md +1 -1
  26. package/assets/skills/read-pdf/SKILL.en.md +1 -1
  27. package/assets/skills/read-pdf/SKILL.zh.md +1 -1
  28. package/assets/skills/research/SKILL.en.md +1 -1
  29. package/assets/skills/research/SKILL.zh.md +1 -1
  30. package/assets/skills/revise/SKILL.en.md +1 -1
  31. package/assets/skills/revise/SKILL.zh.md +1 -1
  32. package/assets/skills/today/SKILL.en.md +1 -1
  33. package/assets/skills/today/SKILL.zh.md +1 -1
  34. package/dist/cli/commands/doctor.d.ts +2 -0
  35. package/dist/cli/commands/doctor.js +34 -11
  36. package/dist/cli/commands/doctor.js.map +1 -1
  37. package/dist/cli/commands/init.js +0 -8
  38. package/dist/cli/commands/init.js.map +1 -1
  39. package/dist/cli/commands/upgrade.js +20 -2
  40. package/dist/cli/commands/upgrade.js.map +1 -1
  41. package/dist/cli/utils/install-assets.js +6 -2
  42. package/dist/cli/utils/install-assets.js.map +1 -1
  43. package/dist/cli/utils/sync-vault.js +1 -28
  44. package/dist/cli/utils/sync-vault.js.map +1 -1
  45. package/dist/config.d.ts +1 -0
  46. package/dist/config.js +2 -0
  47. package/dist/config.js.map +1 -1
  48. package/dist/index.d.ts +1 -1
  49. package/dist/index.js +1 -1
  50. package/dist/server.js +1 -1
  51. package/package.json +7 -4
package/README.md CHANGED
@@ -1,9 +1,13 @@
1
1
  # LifeOS
2
-
2
+ ![LifeOS Example](./example.png)
3
3
  [中文](./README.zh.md) | English
4
4
 
5
5
  LifeOS helps you grow scattered ideas into structured knowledge and truly master it, from quick captures, to brainstorming and deep research, to systematic project planning and knowledge notes, to spaced review and mastery tracking. The goal is not just building a knowledge base, but helping you understand, internalize, and command complex knowledge.
6
6
 
7
+ ## Why Build LifeOS?
8
+
9
+ LifeOS started from a simple goal: package learning workflows, skills, templates, prompts, and a memory system into one complete setup you can use immediately. Instead of assembling your own toolchain from scratch or jumping between disconnected tools, you can initialize once, start working right away, and keep accumulating knowledge, process, and preferences as you go.
10
+
7
11
  ## Core Features
8
12
 
9
13
  ### Memory System
@@ -16,7 +20,7 @@ Session bridges and active-document context persist, so agents do not depend onl
16
20
 
17
21
  #### Project-scoped and skill-bound
18
22
 
19
- The memory system runs around the current LifeOS project in the vault, activates only inside workflows such as `today`, `project`, `research`, `knowledge`, `revise`, and `archive`, and keeps accumulating preferences, decisions, and context.
23
+ The memory system runs around the current LifeOS project in the vault, activates only inside workflows such as `today`, `project`, `research`, `knowledge`, `revise`, `digest`, and `archive`, and keeps accumulating preferences, decisions, and context.
20
24
 
21
25
  #### More controllable than global memory
22
26
 
@@ -34,28 +38,28 @@ LifeOS provides a set of Agent skills designed around the learning process, conn
34
38
 
35
39
  - `/today`, `/brainstorm`, `/ask`: organize the day's focus, clarify questions, and quickly expand ideas
36
40
  - `/project`, `/research`, `/knowledge`: turn a topic into a project, a research report, and structured knowledge notes
41
+ - `/digest`: subscribe to topic updates and generate structured weekly digests from paper sources, RSS, and web search
37
42
  - `/read-pdf`, `/revise`, `/archive`: move from source extraction, to review and reinforcement, to periodic archiving
38
43
 
39
44
  ## Core Components
40
45
 
41
46
  - **Memory system** — Project-scoped and skill-bound, providing vault indexing, session memory, and context assembly for AI agents
42
47
  - **CLI scaffold** — install globally, then use `lifeos init` to bootstrap a complete workspace
43
- - **Skill system** — 9 Agent skills covering diary, projects, research, knowledge curation, review, and more
48
+ - **Skill system** — 10 Agent skills covering daily planning, projects, research, weekly digests, knowledge curation, review, and more
44
49
  - **Templates + Schema** — 8 structured templates + Frontmatter schema for consistent notes
45
50
 
46
51
  ## Quick Start
47
52
 
48
- At the moment, only the Agent CLI workflow has been verified in practice on macOS. The Agent GUI path has not been systematically tested yet, and Windows has not been verified either, so the experience there may not be fully consistent yet.
53
+ LifeOS has been verified to work properly with Claude Code TUI / Codex TUI / OpenCode TUI on macOS, and with OpenCode GUI on Windows. Other desktop GUI apps or platform/client combinations have not been validated yet and may require additional testing.
49
54
 
50
55
  ### Prerequisites
51
56
 
52
- Before starting, make sure Obsidian and at least one of Claude Code CLI / Codex CLI / OpenCode CLI are installed locally.
57
+ Before starting, make sure Obsidian and at least one of Claude Code TUI / Codex TUI / OpenCode TUI / OpenCode GUI are installed locally.
53
58
 
54
59
  | Dependency | Required | Purpose |
55
60
  |---|---|---|
56
- | **Node.js 18+** | Required | Runtime for MCP server and CLI |
57
- | **Git** | Required | Version control for vault data, including the memory DB |
58
- | **Python 3** | Required | PDF extraction (`/read-pdf` skill) |
61
+ | **Node.js 24.14.1+ (LTS)** | Required | Runtime for MCP server and CLI |
62
+ | **Python 3** | Required | PDF extraction (`/read-pdf`) and digest fetch helpers (`/digest`) |
59
63
 
60
64
  `lifeos init` checks all prerequisites before creating the workspace.
61
65
 
@@ -83,6 +87,8 @@ After init, MCP server configs are automatically registered for:
83
87
 
84
88
  Launch any of these tools in the vault directory to use all skills.
85
89
 
90
+ If you want version control for the vault, initialize and manage Git yourself. LifeOS does not create or manage Git metadata for you.
91
+
86
92
  ## CLI Commands
87
93
 
88
94
  ```bash
@@ -101,10 +107,9 @@ Creates a complete LifeOS workspace:
101
107
  - 10 top-level directories plus nested subdirectories
102
108
  - 8 Markdown templates
103
109
  - Frontmatter schema
104
- - 9 AI skills with language-aware assets
110
+ - 10 AI skills with language-aware assets
105
111
  - `CLAUDE.md` agent behavior spec
106
112
  - `lifeos.yaml` config
107
- - Git init plus `.gitignore`
108
113
  - MCP server registration (Claude Code / Codex / OpenCode)
109
114
 
110
115
  ### upgrade
@@ -112,7 +117,7 @@ Creates a complete LifeOS workspace:
112
117
  Upgrades and re-syncs an initialized vault:
113
118
 
114
119
  - **Smart merge**: update unmodified templates, schema files, built-in prompts, and skill files; skip modified ones with a warning
115
- - **Restore missing scaffold**: bring back missing directories and managed files such as the memory directory, `.claude/skills`, `CLAUDE.md`, `AGENTS.md`, `.gitignore`, `.git`, and MCP config entries
120
+ - **Restore missing scaffold**: bring back missing directories and managed files such as the memory directory, `.claude/skills`, `CLAUDE.md`, `AGENTS.md`, and MCP config entries
116
121
  - **Preserve user changes**: built-in files already customized by the user are not force-overwritten
117
122
  - **`--override` force-refreshes resources**: overwrite templates, schema, prompts, skills, `CLAUDE.md`, `AGENTS.md`, and MCP config entries without deleting user notes, resources, `memory.db`, memory-system data, or custom directory/memory settings in `lifeos.yaml`
118
123
 
@@ -139,6 +144,7 @@ This means LifeOS does not lock you into fixed directory names. You can freely a
139
144
  | `/today` | Morning planning: review yesterday, plan today |
140
145
  | `/project` | Idea -> structured project |
141
146
  | `/research` | Topic -> deep research report |
147
+ | `/digest` | Topic subscription -> structured weekly digest |
142
148
  | `/knowledge` | Book/paper -> knowledge note |
143
149
  | `/revise` | Generate quizzes, grade, and track mastery |
144
150
  | `/read-pdf` | PDF -> structured notes |
@@ -165,7 +171,7 @@ Create a `.md` file in your vault's Prompts directory (`{system directory}/Promp
165
171
 
166
172
  ## Tech Stack
167
173
 
168
- - **Runtime:** TypeScript + Node.js 18+
174
+ - **Runtime:** TypeScript + Node.js 24.14.1+ (LTS)
169
175
  - **Database:** SQLite + FTS5 (full-text search)
170
176
  - **Segmentation:** @node-rs/jieba (Chinese tokenization)
171
177
  - **Protocol:** MCP (Model Context Protocol)
@@ -176,8 +182,8 @@ Create a `.md` file in your vault's Prompts directory (`{system directory}/Promp
176
182
  - ✅ LifeOS 1.0 is now basically usable
177
183
  - ✅ The CLI supports directory customization
178
184
  - ✅ The CLI `upgrade` command supports smart updates
179
- - ✅ Agent CLI has been tested on macOS
180
- - Test and support Agent GUI and Windows
185
+ - ✅ Claude Code TUI / Codex TUI / OpenCode TUI on macOS and OpenCode GUI on Windows have been tested
186
+ - The `/digest` skill supports multilingual weekly digests with multi-source paper fetching
181
187
  - ☐ Improve memory-system precision
182
188
  - ☐ Support custom skills
183
189
  - ☐ Support custom workflows
package/README.zh.md CHANGED
@@ -1,9 +1,13 @@
1
1
  # LifeOS
2
-
2
+ ![LifeOS 示例](./example.png)
3
3
  [English](./README.md) | 中文
4
4
 
5
5
  LifeOS 帮助你将碎片灵感发展为结构化知识,并真正掌握它,从随手捕获的想法,到头脑风暴与深度研究,到体系化的项目规划与知识笔记,再到间隔复习与掌握度追踪。目标不只是建立知识库,而是帮你理解、内化和驾驭复杂知识。
6
6
 
7
+ ## 为什么开发 LifeOS?
8
+
9
+ LifeOS 的出发点很直接:把学习工作流、技能、模板、提示词和记忆系统整合成一套可以直接落地的完整方案。你不需要自己从零拼装工具链,也不必在不同工具之间来回切换,初始化后即可开箱即用,并在真实使用中持续沉淀知识、流程与偏好。
10
+
7
11
  ## 核心功能
8
12
 
9
13
  ### 记忆系统
@@ -16,7 +20,7 @@ LifeOS 帮助你将碎片灵感发展为结构化知识,并真正掌握它,
16
20
 
17
21
  #### 项目级、技能绑定
18
22
 
19
- 记忆系统围绕当前 Vault 中的 LifeOS 项目运行,只在 `today`、`project`、`research`、`knowledge`、`revise`、`archive` 等技能工作流里激活,并持续积累偏好、决策和上下文。
23
+ 记忆系统围绕当前 Vault 中的 LifeOS 项目运行,只在 `today`、`project`、`research`、`knowledge`、`revise`、`digest`、`archive` 等技能工作流里激活,并持续积累偏好、决策和上下文。
20
24
 
21
25
  #### 比全局记忆更可控
22
26
 
@@ -34,28 +38,28 @@ LifeOS 提供一组围绕学习过程设计的 Agent 技能,把“输入 ->
34
38
 
35
39
  - `/today`、`/brainstorm`、`/ask`:整理当天重点、澄清问题、快速展开想法
36
40
  - `/project`、`/research`、`/knowledge`:把主题推进成项目、研究报告和知识笔记
41
+ - `/digest`:按主题订阅论文、RSS 与 Web 更新,自动生成结构化信息周报
37
42
  - `/read-pdf`、`/revise`、`/archive`:从资料提取、复习巩固,到定期归档收束
38
43
 
39
44
  ## 核心组件
40
45
 
41
46
  - **记忆系统**:项目级、技能绑定,为 AI Agent 提供 Vault 索引、会话记忆、上下文组装
42
47
  - **CLI 脚手架**:全局安装后使用 `lifeos init` 一键创建工作空间
43
- - **技能系统**:9 个 Agent 技能覆盖日记、项目、研究、知识整理、复习等工作流
48
+ - **技能系统**:10 个 Agent 技能覆盖日记、项目、研究、信息周报、知识整理、复习等工作流
44
49
  - **模板 + 规范**:8 个结构化模板 + Frontmatter 规范,确保笔记一致性
45
50
 
46
51
  ## 快速开始
47
52
 
48
- 目前仅在 macOS 上实际验证过 Agent CLI 流程;Agent GUI 端尚未系统测试,Windows 环境也还未验证,因此这两部分暂时不能保证体验完全一致。
53
+ 目前已确认 macOS 上的 Claude Code TUI / Codex TUI / OpenCode TUI,以及 Windows 上 OpenCode GUI 可以正常使用。其他 GUI 桌面端或平台/客户端组合尚未完成验证,实际兼容性仍需进一步测试。
49
54
 
50
55
  ### 前置要求
51
56
 
52
- 开始前,请确保本机已安装 Obsidian,以及 Claude Code CLI / Codex CLI / OpenCode CLI 中至少一种。
57
+ 开始前,请确保本机已安装 Obsidian,以及 Claude Code TUI / Codex TUI / OpenCode TUI / OpenCode GUI 中至少一种。
53
58
 
54
59
  | 依赖 | 必须 | 用途 |
55
60
  |---|---|---|
56
- | **Node.js 18+** | 必须 | MCP Server 和 CLI 运行环境 |
57
- | **Git** | 必须 | Vault 版本控制(包括记忆数据库) |
58
- | **Python 3** | 必须 | PDF 提取(`/read-pdf` 技能) |
61
+ | **Node.js 24.14.1+ (LTS)** | 必须 | MCP Server 和 CLI 运行环境 |
62
+ | **Python 3** | 必须 | PDF 提取(`/read-pdf`)和信息周报抓取脚本(`/digest`) |
59
63
 
60
64
  `lifeos init` 会在创建工作空间前自动检查所有前置依赖。
61
65
 
@@ -101,7 +105,7 @@ lifeos --version # 查看版本
101
105
  - 10 个顶层目录 + 嵌套子目录
102
106
  - 8 个 Markdown 模板
103
107
  - Frontmatter 规范
104
- - 9 个 AI 技能(按语言自动切换)
108
+ - 10 个 AI 技能(按语言自动切换)
105
109
  - `CLAUDE.md` Agent 行为规范
106
110
  - `lifeos.yaml` 配置文件
107
111
  - Git 初始化 + `.gitignore`
@@ -139,6 +143,7 @@ lifeos upgrade ./my-vault --override
139
143
  | `/today` | 晨间规划:回顾昨日、规划今日 |
140
144
  | `/project` | 想法 → 结构化项目 |
141
145
  | `/research` | 主题 → 深度研究报告 |
146
+ | `/digest` | 主题订阅 → 结构化信息周报 |
142
147
  | `/knowledge` | 书籍/论文 → 知识笔记 |
143
148
  | `/revise` | 生成复习题、批改、追踪掌握度 |
144
149
  | `/read-pdf` | PDF → 结构化笔记 |
@@ -176,8 +181,8 @@ lifeos upgrade ./my-vault --override
176
181
  - ✅ LifeOS 1.0 版本已初步可用
177
182
  - ✅ CLI 支持目录自定义
178
183
  - ✅ CLI upgrade 支持智能更新
179
- - ✅ macOS Agent CLI 已测试
180
- - Agent GUI 和 Windows 测试与支持
184
+ - ✅ 已完成 macOS Claude Code TUI / Codex TUI / OpenCode TUI 与 Windows 上 OpenCode GUI 的验证
185
+ - `/digest` 技能已支持中英双语信息周报与多来源论文抓取
181
186
  - ☐ 强化记忆系统精准性
182
187
  - ☐ 支持自定义技能
183
188
  - ☐ 支持自定义工作流
@@ -6,7 +6,7 @@
6
6
  > The default directory names below come from presets; actual names follow the user's `lifeos.yaml` configuration.
7
7
 
8
8
  # Agent Behavior Guidelines — LifeOS
9
- `v1.0.2`
9
+ `v1.1.0`
10
10
 
11
11
  You are the user's lifelong learning partner. Through **LifeOS**, help the user develop fragmented inspirations into structured knowledge and truly master it — from casually captured ideas, through brainstorming and deep research, to systematic project planning and knowledge notes, then spaced review and mastery tracking. The goal is not just building a knowledge base, but helping the user understand, internalize, and command complex knowledge.
12
12
 
@@ -6,7 +6,7 @@
6
6
  > 以下默认目录名来自 preset,实际名称以用户 Vault 中的 `lifeos.yaml` 为准。
7
7
 
8
8
  # Agent 行为规范 — LifeOS
9
- `v1.0.2`
9
+ `v1.1.0`
10
10
 
11
11
  你是用户的终身学习伙伴。通过 **LifeOS**,帮助用户将碎片灵感发展为结构化知识,并真正掌握它——从随手捕获的想法,到头脑风暴与深度研究,到体系化的项目规划与知识笔记,再到间隔复习与掌握度追踪。目标不只是建立知识库,而是帮用户理解、内化和驾驭复杂知识。
12
12
 
@@ -24,6 +24,7 @@ subdirectories:
24
24
  templates: "模板"
25
25
  schema: "规范"
26
26
  memory: "记忆"
27
+ digest: "信息"
27
28
  prompts: "提示词"
28
29
  archive:
29
30
  projects: "归档/项目"
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: archive
3
3
  description: "Scan and archive completed projects (status:done), consumed drafts (status:researched/projected/knowledged), completed plans (status: done), and diary entries older than the most recent 7 days, moving them into the unified archive structure and updating frontmatter. Never touches pending drafts, active plans, or the most recent 7 days of diary entries. Use this skill when the user wants to clean up the Vault, archive completed work, tidy up, or says '/archive'."
4
- version: 1.0.2
4
+ version: 1.1.0
5
5
  dependencies:
6
6
  templates: []
7
7
  prompts: []
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: archive
3
3
  description: '扫描并归档已完成的项目(status:done)、已消化的草稿(status:researched/projected/knowledged)、已完成的计划(status: done)以及超过最近 7 天的日记,按归档规则移入统一归档目录并更新 frontmatter。不会触碰 pending 草稿、active 计划或最近 7 天的日记。当用户想清理 Vault、归档已完成的工作、整理库、或说"/archive"时使用此技能。'
4
- version: 1.0.2
4
+ version: 1.1.0
5
5
  dependencies:
6
6
  templates: []
7
7
  prompts: []
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: ask
3
3
  description: Quickly answer user questions, retrieving existing Vault notes as needed. Suitable for concept explanations, usage queries, Vault content lookups, PDF page-specific questions, and other single-turn Q&A scenarios. Complex questions will suggest upgrading to /brainstorm or /research.
4
- version: 1.0.2
4
+ version: 1.1.0
5
5
  dependencies:
6
6
  templates:
7
7
  - path: "{system directory}/{templates subdirectory}/Draft_Template.md"
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: ask
3
3
  description: 快速回答用户问题,按需检索 Vault 已有笔记辅助作答。适用于概念解释、用法查询、Vault 内容检索、PDF 指定页面提问等单轮问答场景。当用户提出任何直接问题或说"/ask"时使用此技能。复杂问题会建议升级到 /brainstorm 或 /research。
4
- version: 1.0.2
4
+ version: 1.1.0
5
5
  dependencies:
6
6
  templates:
7
7
  - path: "{系统目录}/{模板子目录}/Draft_Template.md"
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: brainstorm
3
3
  description: Explore and deepen user ideas through multi-turn interactive dialogue, using techniques like 5 Whys, What if, and Devil's Advocate to guide divergent thinking. Upon conclusion, the user can choose to create a project (invoke /project), organize wiki notes, or save as a draft. Suitable when the user wants to discuss an immature idea, needs divergent thinking, or wants to explore the feasibility of a direction.
4
- version: 1.0.2
4
+ version: 1.1.0
5
5
  dependencies:
6
6
  templates:
7
7
  - path: "{system directory}/{templates subdirectory}/Wiki_Template.md"
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: brainstorm
3
3
  description: 通过多轮交互式对话探索和深化用户的想法,使用 5 Whys、What if、Devil's Advocate 等思维技巧引导发散。结束后可选择创建项目(调用 /project)、整理为百科笔记、或保存为草稿。当用户想聊一个还不成熟的想法、需要发散思维、探索某个方向的可行性、或说"/brainstorm"时使用此技能。
4
- version: 1.0.2
4
+ version: 1.1.0
5
5
  dependencies:
6
6
  templates:
7
7
  - path: "{系统目录}/{模板子目录}/Wiki_Template.md"
@@ -0,0 +1,212 @@
1
+ ---
2
+ name: digest
3
+ description: "A general weekly digest skill: on first use, guide the user through creating a topic config note (Paper Sources, RSS, Web search, and more), then automatically fetch updates and write a structured weekly digest into the drafts directory. Supports multiple topics with separate configs and separate outputs. Trigger when the user says '/digest', 'digest', or asks for a weekly digest."
4
+ version: 1.1.0
5
+ dependencies:
6
+ templates: []
7
+ prompts: []
8
+ schemas:
9
+ - path: "{system directory}/{schema subdirectory}/Frontmatter_Schema.md"
10
+ agents: []
11
+ ---
12
+
13
+ > [!config]
14
+ > Path references in this skill use logical names (for example `{drafts directory}`).
15
+ > The Orchestrator resolves actual paths from `lifeos.yaml` and injects them into the context.
16
+ > Path mappings:
17
+ > - `{drafts directory}` → directories.drafts
18
+ > - `{system directory}` → directories.system
19
+ > - `{digest subdirectory}` → subdirectories.system.digest
20
+ > - `{schema subdirectory}` → subdirectories.system.schema
21
+
22
+ You are LifeOS's digest assistant. Your job is to collect recent updates for user-defined topics and produce structured weekly digest notes.
23
+
24
+ **Language rule**: All replies, config notes, and generated digest files must be in English.
25
+
26
+ # Workflow Overview
27
+
28
+ This skill has two run modes:
29
+
30
+ | Mode | Trigger | Behavior |
31
+ |------|---------|----------|
32
+ | **Setup mode** | No config files exist under `{system directory}/{digest subdirectory}/`, or the user explicitly asks for `setup` | Guide the user through creating a topic config note |
33
+ | **Run mode** | A config file already exists | Read the config, fetch updates, and write a weekly digest |
34
+
35
+ # Entry Routing
36
+
37
+ Choose the mode from the user input:
38
+
39
+ ```text
40
+ /digest → Scan all .md configs under {system directory}/{digest subdirectory}/ and run each one
41
+ If the directory is empty or missing → automatically enter Setup mode
42
+ /digest <topic> → Run only the named topic (matched by filename)
43
+ If the file does not exist → automatically enter Setup mode seeded with that topic
44
+ /digest setup → Enter Setup mode and create a new topic config
45
+ /digest setup <topic> → Enter Setup mode seeded with the given topic name
46
+ ```
47
+
48
+ # Setup Mode
49
+
50
+ Follow `references/setup-guide.md` for the conversation flow:
51
+
52
+ 1. **Define the topic**: ask what domain and subareas the user wants to track
53
+ 2. **Understand preferences**: academic vs industry, must-read sources, and focus areas
54
+ 3. **Generate config**: recommend sources and produce a full config note
55
+ 4. **User review**: write the config to `{system directory}/{digest subdirectory}/<TopicName>.md` and ask the user to review it in Obsidian
56
+
57
+ The config note uses Markdown tables plus checkbox switches so the user can edit it directly in Obsidian:
58
+
59
+ - toggle checkboxes to enable or disable modules
60
+ - add or remove table rows to change concrete sources, including `Paper Sources`
61
+ - edit the category table to reshape the digest structure
62
+
63
+ See `references/config-parser.md` for the config note structure.
64
+
65
+ # Run Mode
66
+
67
+ Follow `references/run-pipeline.md` for the fetch pipeline.
68
+
69
+ ### Preflight
70
+
71
+ 1. Verify Python 3 is available: `python3 --version`
72
+ 2. Read and parse the config note according to `references/config-parser.md`
73
+
74
+ ### Execution Pipeline
75
+
76
+ ```text
77
+ Phase 1: Parse config → structured data
78
+ Phase 2: Fetch in parallel
79
+ ├─ Task A: RSS + paper sources → Python script (references/rss-arxiv-script.py)
80
+ ├─ Task B: Web search → WebSearch tool
81
+ ├─ Task C: HuggingFace papers → WebFetch
82
+ └─ Task D: GitHub Trending → WebFetch (optional)
83
+ Phase 3: Merge and deduplicate → classify by category system
84
+ Phase 4: Write digest → {drafts directory}/<TopicName>-MMDD-MMDD.md
85
+ ```
86
+
87
+ ### Python Script Invocation
88
+
89
+ RSS + paper-source fetching runs through the parameterized Python helper. Parse the config, build
90
+ the JSON payload, and pass it through stdin.
91
+
92
+ The `Paper Sources` model now supports:
93
+
94
+ - `arXiv`, `bioRxiv`, `medRxiv`, `ChemRxiv`, `SocArXiv`, `SSRN`
95
+ - each row supplies `Source Type`, `Query`, `Scope`, and `Notes`
96
+ - the helper normalizes each source through a dedicated adapter and returns structured errors per
97
+ source instead of failing the whole run
98
+ - legacy `### arXiv Search` config blocks are still accepted and translated into `arXiv` sources so
99
+ older notes keep working
100
+ - `SocArXiv` results may normalize to `OSF` landing pages when that is the source-hosted record
101
+ - all paper-source adapters stay on a low-request budget: one primary request per source, bounded
102
+ retry only for transient failures, and no pagination
103
+
104
+ For arXiv specifically:
105
+
106
+ - configured arXiv queries must be English
107
+ - the helper fetches recent category results first, then filters locally
108
+ - if the official arXiv path fails, it may fall back to OpenAlex but only keep arXiv-mappable
109
+ papers
110
+
111
+ Invoke it like this:
112
+
113
+ ```bash
114
+ echo '<json_input>' | python3 .agents/skills/digest/references/rss-arxiv-script.py
115
+ ```
116
+
117
+ JSON input shape:
118
+
119
+ ```json
120
+ {
121
+ "language": "en",
122
+ "rss": {
123
+ "enabled": true,
124
+ "feeds": [{"name": "Source name", "url": "https://..."}]
125
+ },
126
+ "papers": {
127
+ "enabled": true,
128
+ "sources": [
129
+ {
130
+ "source_type": "arXiv",
131
+ "query": "\"llm agent\"",
132
+ "scope": "cs.AI",
133
+ "notes": "Core technical papers"
134
+ },
135
+ {
136
+ "source_type": "bioRxiv",
137
+ "query": "single-cell",
138
+ "scope": "Neuroscience",
139
+ "notes": "Biomedical preprints"
140
+ }
141
+ ]
142
+ },
143
+ "days": 7
144
+ }
145
+ ```
146
+
147
+ The helper returns `rss_articles`, normalized paper results, `stats`, and structured `errors`.
148
+
149
+ ### Digest Output
150
+
151
+ Write the digest to `{drafts directory}/<TopicName>-MMDD-MMDD.md`:
152
+
153
+ ```yaml
154
+ ---
155
+ title: "{Topic} Weekly Digest · YYYY-MM-DD ~ YYYY-MM-DD"
156
+ type: draft
157
+ created: "YYYY-MM-DD"
158
+ status: pending
159
+ tags: [digest, {topic-tag}, weekly-digest]
160
+ aliases: []
161
+ ---
162
+ ```
163
+
164
+ Organize the body using the configured category system. Each item should have a 1-2 sentence English summary plus the source link. Omit empty categories. End with a source list.
165
+
166
+ # File Paths
167
+
168
+ | Content | Path |
169
+ |---------|------|
170
+ | Topic config note | `{system directory}/{digest subdirectory}/<TopicName>.md` |
171
+ | Weekly digest output | `{drafts directory}/<TopicName>-MMDD-MMDD.md` |
172
+ | Parsing rules | `references/config-parser.md` |
173
+ | Setup guide | `references/setup-guide.md` |
174
+ | Run pipeline | `references/run-pipeline.md` |
175
+ | Python helper | `references/rss-arxiv-script.py` |
176
+
177
+ # Memory System Integration
178
+
179
+ > Common protocols (file change notification, skill completion, session wrap-up) are documented in `_shared/memory-protocol.md`. Only digest-specific behavior is listed here.
180
+
181
+ ### File Change Notification
182
+
183
+ After the digest file is written into the Vault, call:
184
+
185
+ ```text
186
+ memory_notify(file_path="{drafts directory}/<TopicName>-MMDD-MMDD.md")
187
+ ```
188
+
189
+ ### Skill Completion
190
+
191
+ ```text
192
+ memory_skill_complete(
193
+ skill_name="digest",
194
+ summary="Generated {topic} weekly digest MMDD-MMDD",
195
+ related_files=["{drafts directory}/<TopicName>-MMDD-MMDD.md"],
196
+ scope="digest",
197
+ refresh_targets=["TaskBoard", "UserProfile"]
198
+ )
199
+ ```
200
+
201
+ ### Setup Mode Completion
202
+
203
+ After creating the config note, also record a decision:
204
+
205
+ ```text
206
+ memory_log(
207
+ entry_type="decision",
208
+ summary="Created {topic} digest subscription config",
209
+ importance=2,
210
+ scope="digest"
211
+ )
212
+ ```