Not in the top 1,000 by GitHub stars
iBlinkQ/project-cairn
Turn project work into reusable knowledge — an AI-agent skill for Claude Code & Codex
History
Review weekly changes to SKILL.md before updating. Dates mark the weeks in which we observed each version; checks apply to the recorded commits.
View weekly changes
SKILL.md
Week of Nov 2, 2026 · +0 / −0 lines
Before Network or broad shell → After Network or broad shell
b295e14317a4 → b295e14317a4
Week of Oct 26, 2026 · Line counts unavailable
Before Not checked yet → After Network or broad shell
First observation → b295e14317a4
No earlier version was observed for comparison.
View on GitHubAdd to my skills
Verified commit b295e14317a4a3fed5e728563eff4d38cf6ec561
git clone --filter=blob:none --no-checkout https://github.com/iBlinkQ/project-cairn.git .hotskills/iblinkq-project-cairn && git -C .hotskills/iblinkq-project-cairn checkout --detach b295e14317a4a3fed5e728563eff4d38cf6ec561
# Copy each selected skill directory from .hotskills/iblinkq-project-cairn into .agents/skills/<skill-name>/252GitHub stars
0stars in 7 days
1skill in this repository
3commits in 30 days
Heat
1.3- Star growth, last 7 daysNot available
- Star growth, last 24 hoursNot available
- Rank movement, last 7 daysNot available
- Commits, last 30 daysNot available
- Accounts asking about it through MCP, last 7 daysNot available
- Hot votes this weekNot available
Heat never changes the order by stars, and sponsorship never touches it. How heat works
Stars over time
30-day change not yet available: not enough history.
Individual skills in this repository
How it works
project-cairn
When your agent uses it
Standardize how an AI-collaboration project turns work into reusable knowledge. Use when initializing or retrofitting Project Cairn in a project, recording progress after meaningful work, maintaining AGENTS/CLAUDE/cairn docs, auditing project knowledge for drift or missing records, pulling and citing external knowledge, or graduating validated project experience into a reusable knowledge base.
What it loads into context
Frontmatter
82 tokensAlways available to the agent
SKILL.md
769 tokensWhen the skill is activated
Reference documents
29,336 tokensLoaded on request
Token counts are estimates. Scripts run separately; they are not counted as reference context.
The playbook
- Routing
- Templates
- Boundaries
Scripts executed separately
scripts/.gitkeepscripts/lark-preflight.shscripts/lark-wiki-graduate.shscripts/notion-graduate-batch.pyscripts/notion-graduate.shscripts/notion-init-db.shscripts/notion-preflight.shscripts/obsidian-graduate.shscripts/obsidian-preflight.shtests/test_note_type.pytests/test_notion_graduate_batch.py
Files
LICENSEasset1,064 bytesREADME.mddoc11,968 bytesREADME.zh-CN.mddoc11,039 bytesSKILL.mdcore3,461 bytesagents/openai.yamlasset204 bytesassets/templates/AGENTS.mddoc4,069 bytesassets/templates/CLAUDE.mddoc11 bytesassets/templates/Cited.mddoc322 bytesassets/templates/LOG.mddoc425 bytesassets/templates/ROADMAP.mddoc142 bytesassets/templates/config.yamlasset3,689 bytesassets/templates/topic.mddoc448 bytesassets/templates/user-config.yamlasset1,571 bytesdocs/assets/favicon/apple-touch-icon.pngasset4,305 bytesdocs/assets/favicon/favicon.icoasset1,784 bytesdocs/assets/favicon/favicon.svgasset1,152 bytesdocs/assets/logo/cairn-icon-black.svgasset1,076 bytesdocs/assets/screenshots/project-cairn-ecosystem-en.pngasset2,214,510 bytesdocs/assets/screenshots/project-cairn-ecosystem-zh-CN.pngasset2,166,170 bytesdocs/assets/screenshots/project-cairn-overview-en.pngasset1,596,845 bytesdocs/assets/screenshots/project-cairn-overview-zh-CN.pngasset1,645,430 bytesdocs/index.htmlasset423,367 bytesreferences/audit.mddoc3,501 bytesreferences/branch-closure.mddoc1,759 bytesreferences/consume.mddoc5,213 bytesreferences/frontmatter.mddoc6,382 bytesreferences/graduation.mddoc9,066 bytesreferences/graduation/lark-wiki.mddoc3,878 bytesreferences/graduation/notion.mddoc4,727 bytesreferences/graduation/obsidian.mddoc3,450 bytesreferences/init.mddoc24,468 bytesreferences/maintenance.mddoc4,957 bytesreferences/provider-interface.mddoc15,550 bytesreferences/upgrade.mddoc15,539 bytesreferences/zh-glossary.mddoc1,700 bytesscripts/.gitkeepruns1 bytesscripts/lark-preflight.shruns4,942 bytesscripts/lark-wiki-graduate.shruns14,864 bytesscripts/notion-graduate-batch.pyruns14,620 bytesscripts/notion-graduate.shruns14,111 bytesscripts/notion-init-db.shruns4,537 bytesscripts/notion-preflight.shruns6,701 bytesscripts/obsidian-graduate.shruns11,237 bytesscripts/obsidian-preflight.shruns7,153 bytestests/test_note_type.pyruns15,878 bytestests/test_notion_graduate_batch.pyruns3,363 bytes
Read SKILL.md
# Project Cairn
Project Cairn gives AI-collaboration projects a durable way to keep and reuse what they learn while doing real work. The **Skill** supplies the method, **AGENTS.md** carries always-read project rules, and **`.cairn/config.yaml`** stores machine-readable configuration.
This Skill is documentation-first. It provides instructions, templates, references, and provider adapters. It has no CLI, MCP server, background hook, chat-end trigger, automatic provider write, or automatic history migration. Routine maintenance happens during normal work because `AGENTS.md` carries the rules. Provider writes require human confirmation.
## Routing
Load exactly the reference you need:
- `references/init.md` — initialize, retrofit, bootstrap, or set up Project Cairn in a project.
- `references/consume.md` — pull, cite, reuse, or apply external knowledge from the configured knowledge base.
- `references/maintenance.md` — record progress, update LOG, update ROADMAP, maintain topic notes, or apply Cairn rules after work.
- `references/audit.md` — inspect, audit, validate, clean up, or find missing project knowledge records.Skills included
- project-cairn
Repository facts
- License
- MIT
- Created
- Jul 1, 2026
- Last pushed
- Nov 5, 2026
- Forks
- 48
- Open issues
- 1
- Project activity
- Active
Before you install
Network or broad shellAutomated signals, not a guarantee
Checked Nov 5, 2026
Not fully analyzed: some files were too long, unreadable or missing. This never lowers the level.
Show 9 notes
docs/index.html:49Analysis incomplete: physical or joined line exceeds character limitdocs/index.html:47Analysis incomplete: physical or joined line exceeds character limitdocs/index.html:48Analysis incomplete: physical or joined line exceeds character limitdocs/index.html:768Analysis incomplete: physical or joined line exceeds character limitdocs/index.html:766Analysis incomplete: physical or joined line exceeds character limitdocs/index.html:767Analysis incomplete: physical or joined line exceeds character limitdocs/index.html:1403Analysis incomplete: physical or joined line exceeds character limitdocs/index.html:1401Analysis incomplete: physical or joined line exceeds character limitdocs/index.html:1402Analysis incomplete: physical or joined line exceeds character limit
- No broad tool permissions
- 9 dangerous shell commandsin 6 files: scripts/notion-graduate.sh:174 references/init.md:57 references/upgrade.md:104 and 3 more
- 242 network referencesin 18 files: docs/index.html:766 scripts/notion-graduate.sh:4 tests/test_note_type.py:34 and 15 more
- No hidden or obfuscated text
- No instruction overrides
- 11 executable scriptsin 11 files: scripts/.gitkeep:1 scripts/lark-preflight.sh:1 scripts/lark-wiki-graduate.sh:1 and 8 more
- 38 references to secretsin 7 files: scripts/lark-wiki-graduate.sh:114 scripts/notion-graduate.sh:23 scripts/notion-preflight.sh:59 and 4 more
- No requests to vote in Hot
Show all 300 signals by file
README.md
- Network accessline 7
[Open the interactive guide to learn more about the Skill](https://iblinkq.github.io/project-cairn/) - Network accessline 9
[](https://iblinkq.github.io/project-cairn/) - Network accessline 43
git clone https://github.com/iBlinkQ/project-cairn.git ~/.claude/skills/project-cairn - Network accessline 49
git clone https://github.com/iBlinkQ/project-cairn.git ~/.agents/skills/project-cairn - Network accessline 54
1. Download the [Project Cairn ZIP](https://github.com/iBlinkQ/project-cairn/archive/refs/heads/main.zip). - Network accessline 58
See the [official WorkBuddy skill guide](https://www.workbuddy.ai/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market) for the installation interface. - Network accessline 95
The interactive overview expands this journey into T0 through T8, including roadmap maintenance, audit, and re-graduation: [explore the full flow](https://iblinkq.github.io/project-cairn/). - Network accessline 113
Topic notes use Markdown and YAML frontmatter with at least a `type` field, following the minimal convention of Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve - Network accessline 147
| Tool or approach | Main job | Relationship to Cairn | |---|---|---| | [LLM Wiki](https://github.com/karpathy) | Organize source material you have read into a wiki | LLM Wiki focuses on source knowledge; Cairn focuses on knowledge learned - Network accessline 148
|---|---|---| | [LLM Wiki](https://github.com/karpathy) | Organize source material you have read into a wiki | LLM Wiki focuses on source knowledge; Cairn focuses on knowledge learned through project work | | [Open Knowledge Format](https:/ - Network accessline 149
| [LLM Wiki](https://github.com/karpathy) | Organize source material you have read into a wiki | LLM Wiki focuses on source knowledge; Cairn focuses on knowledge learned through project work | - Network accessline 150
| [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) | Make knowledge files exchangeable by people and machines | OKF concerns format; Cairn concerns formati - Network accessline 152
| [superpowers](https://github.com/obra/superpowers) | Make delivery more reliable through specs, plans, tests, and review | superpowers manages the process; Cairn keeps the stable conclusions learned from it |
README.zh-CN.md
- Network accessline 7
[打开交互说明页面，了解 Skill 详情](https://iblinkq.github.io/project-cairn/) - Network accessline 9
[](https://iblinkq.github.io/project-cairn/) - Network accessline 43
git clone https://github.com/iBlinkQ/project-cairn.git ~/.claude/skills/project-cairn - Network accessline 49
git clone https://github.com/iBlinkQ/project-cairn.git ~/.agents/skills/project-cairn - Network accessline 54
1. 下载 [Project Cairn ZIP](https://github.com/iBlinkQ/project-cairn/archive/refs/heads/main.zip)。 - Network accessline 58
操作入口见 [WorkBuddy 官方 Skill 文档](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market)。 - Network accessline 95
交互式页面把完整过程展开为 T0 到 T8 九个步骤，包括路线图维护、定期审查和再次毕业：[查看完整流程](https://iblinkq.github.io/project-cairn/)。 - Network accessline 113
主题文档使用 Markdown 与 YAML frontmatter，至少包含一个 `type` 字段，对齐 Google [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) 的最小约定。这不等于完整实现 OKF bundle。新建项目主题固定使用 `projec - Network accessline 147
| 工具或方法 | 它主要解决什么 | 与 Cairn 的关系 | |---|---|---| | [LLM Wiki](https://github.com/karpathy) | 把读过的原始资料整理成 wiki | LLM Wiki 偏资料知识化，Cairn 偏项目经验知识化 | - Network accessline 148
|---|---|---| | [LLM Wiki](https://github.com/karpathy) | 把读过的原始资料整理成 wiki | LLM Wiki 偏资料知识化，Cairn 偏项目经验知识化 | | [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sha - Network accessline 149
| [LLM Wiki](https://github.com/karpathy) | 把读过的原始资料整理成 wiki | LLM Wiki 偏资料知识化，Cairn 偏项目经验知识化 | - Network accessline 150
| [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) | 让知识文件可以被人和机器交换 | OKF 是格式方向，Cairn 管形成、维护、毕业和复用 | - Network accessline 152
| [superpowers](https://github.com/obra/superpowers) | 用 spec、plan、测试和评审把工作做稳 | superpowers 管过程，Cairn 从过程中留下稳定结论 |
assets/templates/config.yaml
- Network accessline 58
# parent_page_id: "<page the DB lives under>" # frontmatter_mode: properties # frontmatter -> DB properties, not YAML # transport: rest # direct REST via curl (ntn CLI is proxy-unreliable) - Network accessline 59
# frontmatter_mode: properties # frontmatter -> DB properties, not YAML # transport: rest # direct REST via curl (ntn CLI is proxy-unreliable) # api: native - Network accessline 60
# transport: rest # direct REST via curl (ntn CLI is proxy-unreliable)
docs/assets/favicon/favicon.svg
- Network accessline 1
<svg viewBox="0 0 232 232" xmlns="http://www.w3.org/2000/svg">
docs/assets/logo/cairn-icon-black.svg
- Network accessline 1
<svg viewBox="0 0 232 232" xmlns="http://www.w3.org/2000/svg">
docs/index.html
- Network accessline 766
<g fill="#f5fbff"><rect x="6" y="4" width="1" height="1"/><rect x="9" y="4" width="1" height="1"/></g> </svg>OpenClaw</span> <span class="chip"><svg aria-hidden="true" viewBox="0 0 40 40" fill="none" xmlns="http://www.w3.org - Network accessline 767
</svg>OpenClaw</span> <span class="chip"><svg aria-hidden="true" viewBox="0 0 40 40" fill="none" xmlns="http://www.w3.org/2000/svg"><g clip-path="url(#clip0_542_3370)"><rect width="40" height="40" rx="20" fill="url(#paint0_linear_54 - Network accessline 768
<span class="chip"><svg aria-hidden="true" viewBox="0 0 40 40" fill="none" xmlns="http://www.w3.org/2000/svg"><g clip-path="url(#clip0_542_3370)"><rect width="40" height="40" rx="20" fill="url(#paint0_linear_542_3370)"/><g filter="url(#filt - Network accessline 999
<!-- ================= Skill CTA ================= --> <div class="cta"> <a class="cta-btn" href="https://github.com/iBlinkQ/project-cairn" target="_blank" rel="noopener"> - Network accessline 1000
<div class="cta"> <a class="cta-btn" href="https://github.com/iBlinkQ/project-cairn" target="_blank" rel="noopener"> <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M12 .297c-6.63 0-12 5.373 - Network accessline 1001
<a class="cta-btn" href="https://github.com/iBlinkQ/project-cairn" target="_blank" rel="noopener"> - Network accessline 1002
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18. - Network accessline 1010
<div class="author"> <span class="aname" data-i18n="authorBy">作者 · Blink</span> <a href="https://v.douyin.com/nywBZQ1D1vw/" target="_blank" rel="noopener"> - Network accessline 1011
<span class="aname" data-i18n="authorBy">作者 · Blink</span> <a href="https://v.douyin.com/nywBZQ1D1vw/" target="_blank" rel="noopener"> <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M12.525 - Network accessline 1012
<a href="https://v.douyin.com/nywBZQ1D1vw/" target="_blank" rel="noopener"> - Network accessline 1013
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M12.525.02c1.31-.02 2.61-.01 3.91-.02.08 1.53.63 3.09 1.75 4.17 1.12 1.11 2.7 1.62 4.24 1.79v4.03c-1.44-.05-2.89-.35-4.2-.97-.57-.26-1.1-.59-1.62-.93-.0 - Network accessline 1014
<span data-i18n="authorDouyin">抖音</span> </a> <a href="https://b23.tv/xxXbN7B" target="_blank" rel="noopener"> - Network accessline 1015
</a> <a href="https://b23.tv/xxXbN7B" target="_blank" rel="noopener"> <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M17.813 4.653h.854c1.51.054 2.769.578 3.773 1.574 1.004.995 1.524 2.249 - Network accessline 1016
<a href="https://b23.tv/xxXbN7B" target="_blank" rel="noopener"> - Network accessline 1017
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M17.813 4.653h.854c1.51.054 2.769.578 3.773 1.574 1.004.995 1.524 2.249 1.56 3.76v7.36c-.036 1.51-.556 2.769-1.56 3.773s-2.262 1.524-3.773 1.56H5.333c-1 - Network accessline 1018
<span data-i18n="authorBili">B 站</span> </a> <a href="https://www.youtube.com/@blinkq3370" target="_blank" rel="noopener"> - Network accessline 1019
</a> <a href="https://www.youtube.com/@blinkq3370" target="_blank" rel="noopener"> <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M23.498 6.186a3.016 3.016 0 0 0-2.122-2.136C19.505 3.545 12 - Network accessline 1020
<a href="https://www.youtube.com/@blinkq3370" target="_blank" rel="noopener"> - Network accessline 1021
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M23.498 6.186a3.016 3.016 0 0 0-2.122-2.136C19.505 3.545 12 3.545 12 3.545s-7.505 0-9.377.505A3.017 3.017 0 0 0 .502 6.186C0 8.07 0 12 0 12s0 3.93.502 5 - Network accessline 1022
<span>YouTube</span> </a> <a href="https://github.com/iBlinkQ" target="_blank" rel="noopener"> - Network accessline 1023
</a> <a href="https://github.com/iBlinkQ" target="_blank" rel="noopener"> <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113 - Network accessline 1024
<a href="https://github.com/iBlinkQ" target="_blank" rel="noopener"> - Network accessline 1025
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18. - Network accessline 1144
{k:"T1", lab:"首次推进", stamp:"log", title:"cairn/LOG.md 写下第一条", trig:"第一次实质推进", files:[], glow:["f-log"], flows:[["f-agents","f-log"]], body:"<b>cairn/LOG.md</b> 是项目的时序日志，回答『发生了什么』：倒序排列，最新在最上。亮点：<b>单条 ≤ 20 行、只写摘要 + 指针</b>——结论沉入主题文档（T4）， - Network accessline 1145
trig:"第一次实质推进", files:[], glow:["f-log"], flows:[["f-agents","f-log"]], body:"<b>cairn/LOG.md</b> 是项目的时序日志，回答『发生了什么』：倒序排列，最新在最上。亮点：<b>单条 ≤ 20 行、只写摘要 + 指针</b>——结论沉入主题文档（T4），日志保持轻快，随时可供人与 Agent 扫读。<a href='https://cloud.google.com/blog/pro - Network accessline 1146
body:"<b>cairn/LOG.md</b> 是项目的时序日志，回答『发生了什么』：倒序排列，最新在最上。亮点：<b>单条 ≤ 20 行、只写摘要 + 指针</b>——结论沉入主题文档（T4），日志保持轻快，随时可供人与 Agent 扫读。<a href='https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing - Network accessline 1148
{k:"T2", lab:"目标生长", stamp:"roadmap", title:"cairn/ROADMAP.md 诞生", trig:"出现一次会话做不完的目标", files:["f-roadmap"], glow:["f-roadmap"], flows:[["f-agents","f-roadmap"]], body:"<b>cairn/ROADMAP.md</b> 是项目的路线图：里程碑、当前焦点、下一步、开放问题。它和 LOG 互为镜像——RO - Network accessline 1149
trig:"出现一次会话做不完的目标", files:["f-roadmap"], glow:["f-roadmap"], flows:[["f-agents","f-roadmap"]], body:"<b>cairn/ROADMAP.md</b> 是项目的路线图：里程碑、当前焦点、下一步、开放问题。它和 LOG 互为镜像——ROADMAP 朝前看路线，LOG 朝后看足迹。与 <a href='https://github.com/obra/superpowers' - Network accessline 1150
body:"<b>cairn/ROADMAP.md</b> 是项目的路线图：里程碑、当前焦点、下一步、开放问题。它和 LOG 互为镜像——ROADMAP 朝前看路线，LOG 朝后看足迹。与 <a href='https://github.com/obra/superpowers' target='_blank' style='color:var(--accent);'>superpowers</a> 的 <code>plans/</code> 管理对象不同：ROADMAP 管 - Network accessline 1152
{k:"T3", lab:"外部资料", stamp:"raw", title:"Reference/ 接收原始输入", trig:"收到第一份外部材料", files:["f-ref"], glow:["f-ref"], flows:[["f-ext","f-ref"]], body:"<b>cairn/Reference/</b> 收纳外部原始输入：甲方需求、模板、报表样例、PDF / 图片等，原样存放。对应 <a href='https://gist.git - Network accessline 1153
trig:"收到第一份外部材料", files:["f-ref"], glow:["f-ref"], flows:[["f-ext","f-ref"]], body:"<b>cairn/Reference/</b> 收纳外部原始输入：甲方需求、模板、报表样例、PDF / 图片等，原样存放。对应 <a href='https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f' target='_blan - Network accessline 1154
body:"<b>cairn/Reference/</b> 收纳外部原始输入：甲方需求、模板、报表样例、PDF / 图片等，原样存放。对应 <a href='https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f' target='_blank' style='color:var(--accent);'>Karpathy LLM-wiki</a> 的 Raw Sources——它们是知识的原材料，蒸馏 - Network accessline 1156
{k:"T4", lab:"知识沉淀", stamp:"distill", title:"结论沉入 cairn/<主题>.md", trig:"形成值得保留的结论", files:["f-topic"], glow:["f-topic","f-log"], flows:[["f-log","f-topic"]], body:"这是<b>对话自发渠道</b>：与 Agent 交流中形成的踩坑经验、关键决策、探索成果、灵感洞见，都沉入 <b>cairn/<主题& - Network accessline 1157
trig:"形成值得保留的结论", files:["f-topic"], glow:["f-topic","f-log"], flows:[["f-log","f-topic"]], body:"这是<b>对话自发渠道</b>：与 Agent 交流中形成的踩坑经验、关键决策、探索成果、灵感洞见，都沉入 <b>cairn/<主题>.md</b>——一个主题一篇文档、原地更新，始终代表该主题的最新结论，想知道现状读这一篇就够。主题文档采用 Google <a h - Network accessline 1158
body:"这是<b>对话自发渠道</b>：与 Agent 交流中形成的踩坑经验、关键决策、探索成果、灵感洞见，都沉入 <b>cairn/<主题>.md</b>——一个主题一篇文档、原地更新，始终代表该主题的最新结论，想知道现状读这一篇就够。主题文档采用 Google <a href='https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-im - Network accessline 1160
{k:"T5", lab:"过程汲取", stamp:"external process", title:"外部过程结论进入 Cairn", trig:"设计 / 评审 / 实现过程形成稳定结论", files:[], glow:["f-log","f-topic"], flows:[["f-proc","f-log"],["f-proc","f-topic"]], body:"这是与 T4 并行的<b>过程文档渠道</b>：Cairn 也能从项目中的其他过程文档 - Network accessline 1161
trig:"设计 / 评审 / 实现过程形成稳定结论", files:[], glow:["f-log","f-topic"], flows:[["f-proc","f-log"],["f-proc","f-topic"]], body:"这是与 T4 并行的<b>过程文档渠道</b>：Cairn 也能从项目中的其他过程文档里汲取知识——例如 <a href='https://github.com/obra/superpowers' target='_blank' st - Network accessline 1162
body:"这是与 T4 并行的<b>过程文档渠道</b>：Cairn 也能从项目中的其他过程文档里汲取知识——例如 <a href='https://github.com/obra/superpowers' target='_blank' style='color:var(--accent);'>superpowers</a> 的设计文档 / 实施计划、人工评审意见、会议讨论、实现复盘。两条渠道汇入同一批主题文档，与 superpowers 等过程类 skill 互补：<b - Network accessline 1164
{k:"T6", lab:"知识毕业", stamp:"cairn graduate", title:"graduate：经验蒸馏进知识库", trig:"知识被验证的那一刻", files:["f-index","w1","w2","w3","w4","w5"], glow:["f-topic"], arrows:["a-grad"], body:"<b>graduate</b> 把项目里验证过的经验蒸馏成原子化主题笔记，写入你的知识库（Obsidian / N - Network accessline 1165
trig:"知识被验证的那一刻", files:["f-index","w1","w2","w3","w4","w5"], glow:["f-topic"], arrows:["a-grad"], body:"<b>graduate</b> 把项目里验证过的经验蒸馏成原子化主题笔记，写入你的知识库（Obsidian / Notion / 飞书 Wiki 均已验证，可插拔更多目标），并更新 <b>INDEX.md</b>。亮点是完整溯源：<code>graduated_f - Network accessline 1166
body:"<b>graduate</b> 把项目里验证过的经验蒸馏成原子化主题笔记，写入你的知识库（Obsidian / Notion / 飞书 Wiki 均已验证，可插拔更多目标），并更新 <b>INDEX.md</b>。亮点是完整溯源：<code>graduated_from</code> 记录来源项目与源文档，<code>contributors</code> / <code>graduated_by</code> 记录参与者与确认者——每条知识都查得到出处。知识库层 - Network accessline 1168
{k:"T7", lab:"定期体检", stamp:"cairn audit", title:"audit：结构与知识体检", trig:"定期 / 手动", files:[], glow:["f-log","f-topic"], arrows:[], audit:true, body:"<b>audit</b> 给项目层和知识库层做体检：矛盾结论、断链、超载日志、缺失溯源、过期毕业、实例漂移，一次扫出来。思路承自 <a href='https://gist.g - Network accessline 1169
trig:"定期 / 手动", files:[], glow:["f-log","f-topic"], arrows:[], audit:true, body:"<b>audit</b> 给项目层和知识库层做体检：矛盾结论、断链、超载日志、缺失溯源、过期毕业、实例漂移，一次扫出来。思路承自 <a href='https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f' target='_blank' - Network accessline 1170
body:"<b>audit</b> 给项目层和知识库层做体检：矛盾结论、断链、超载日志、缺失溯源、过期毕业、实例漂移，一次扫出来。思路承自 <a href='https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f' target='_blank' style='color:var(--accent);'>Karpathy LLM-wiki</a> 的 Lint 与 <a href='https:// - Network accessline 1271
side:"You trigger it: say 'initialize Project Cairn' to your agent. Init is interactive: the agent confirms project positioning, Git commit policy and graduation target(s) (Obsidian / Notion / Lark) with you, then writes all the files itsel - Network accessline 1272
{lab:"First progress", title:"Write the first cairn/LOG.md entry", trig:"First substantive progress", body:"<b>cairn/LOG.md</b> is the project's timeline log — it answers 'what happened', newest entry on top. The highlight: <b>≤ 20 lines - Network accessline 1273
body:"<b>cairn/LOG.md</b> is the project's timeline log — it answers 'what happened', newest entry on top. The highlight: <b>≤ 20 lines each, summary + pointer only</b> — conclusions sink into topic docs (T4), keeping the log light and scan - Network accessline 1274
side:"Done by the agent automatically: the standing rules in AGENTS.md make it prepend an entry after every substantive step — what was done, what was decided, which doc holds the detail. Append only, never rewrite history; conclusions go t - Network accessline 1275
{lab:"Goal grows", title:"cairn/ROADMAP.md is born", trig:"A goal that outlasts one session", body:"<b>cairn/ROADMAP.md</b> is the project's roadmap: milestones, current focus, next step, open questions. It mirrors LOG — ROADMAP looks fo - Network accessline 1276
body:"<b>cairn/ROADMAP.md</b> is the project's roadmap: milestones, current focus, next step, open questions. It mirrors LOG — ROADMAP looks forward at the route, LOG looks back at the footprints. It manages a different object than <a href= - Network accessline 1277
side:"Maintained by the agent automatically: created when a goal outlasts one session, updated in place as goals advance — milestones ticked, current focus refreshed. Keep it lean: details go to topic docs, not the roadmap."}, {lab:"Exter - Network accessline 1278
{lab:"External material", title:"Reference/ receives raw input", trig:"First external material arrives", body:"<b>cairn/Reference/</b> holds external raw input: client requirements, templates, sample reports, PDFs / images, stored as-is. - Network accessline 1279
body:"<b>cairn/Reference/</b> holds external raw input: client requirements, templates, sample reports, PDFs / images, stored as-is. It mirrors <a href='https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f' target='_blank' styl - Network accessline 1280
side:"You hand material to the project; the agent files it into Reference/ (the folder is created when the first item arrives). <b>In only, never edited</b> — originals stay pristine; the agent writes its understanding and conclusions into - Network accessline 1281
{lab:"Knowledge sinks", title:"Conclusion sinks into cairn/<topic>.md", trig:"A conclusion worth keeping forms", body:"This is the <b>conversation-born channel</b>: pitfall lessons, key decisions, exploration findings and sparks of - Network accessline 1282
body:"This is the <b>conversation-born channel</b>: pitfall lessons, key decisions, exploration findings and sparks of insight formed while working with the agent sink into <b>cairn/<topic>.md</b> — one doc per topic, updated in place - Network accessline 1283
side:"The agent sediments automatically the moment a conclusion forms: create the topic doc if it doesn't exist, update it in place if it does; LOG keeps a one-line pointer. Sub-type with <code>contains</code> (e.g. <code>lesson</code>); re - Network accessline 1284
{lab:"Process harvest", title:"External process conclusions enter Cairn", trig:"Design / review / build yields a stable conclusion", body:"The <b>process-artifact channel</b>, parallel to T4: Cairn also harvests knowledge from the projec - Network accessline 1285
body:"The <b>process-artifact channel</b>, parallel to T4: Cairn also harvests knowledge from the project's other process documents — e.g. <a href='https://github.com/obra/superpowers' target='_blank' style='color:var(--accent);'>superpower - Network accessline 1286
side:"Done by the agent automatically: when a conclusion in a process document is stable / validated, it leaves a one-line pointer in LOG and distills the conclusion into its topic doc. Only the conclusion moves — the process document itsel - Network accessline 1287
{lab:"Graduation", title:"graduate: distill experience into the vault", trig:"The moment knowledge is validated", body:"<b>graduate</b> distills validated project experience into an atomic topic note in your vault (Obsidian / Notion / La - Network accessline 1288
body:"<b>graduate</b> distills validated project experience into an atomic topic note in your vault (Obsidian / Notion / Lark Wiki all validated, pluggable to more targets) and updates <b>INDEX.md</b>. The highlight is full provenance: <cod - Network accessline 1289
side:"The agent spots the moment and proposes; <b>you confirm before anything is written to the vault</b>. The moment is 'knowledge validated': pitfall solved, solution proven, holds in another project too — graduate on the spot, don't wait - Network accessline 1290
{lab:"Periodic audit", title:"audit: structure & knowledge check-up", trig:"Scheduled / manual", body:"<b>audit</b> checks up both the project layer and the vault: contradictory conclusions, broken links, overloaded logs, missing provena - Network accessline 1291
body:"<b>audit</b> checks up both the project layer and the vault: contradictory conclusions, broken links, overloaded logs, missing provenance, stale graduations, instance drift — surfaced in one sweep. The approach follows <a href='https: - Network accessline 1522
/* ============ 项目目录内流向箭头（左侧实心曲线 + 流动圆点） ============ */ const SVGNS="http://www.w3.org/2000/svg"; - Network accessline 1523
const SVGNS="http://www.w3.org/2000/svg";
references/graduation/notion.md
- Network accessline 10
- **Data model = database.** The DB is the knowledge-base container AND the INDEX (its views/properties are the index) — so there is **no `update_index` step** and no INDEX page to append into. Each graduated note is one DB row (page). Fron - Network accessline 11
- **Transport = direct REST (curl), not the `ntn` CLI.** `ntn` fetches an OpenAPI spec to resolve endpoints, does not honor `HTTPS_PROXY`, and fails `PATCH`/`query` behind a proxy. Direct REST via curl honors the proxy; wrap every request i
references/init.md
- Dangerous shell operationline 57
- **A rule cannot protect a path git already tracks — say so instead.** `.gitignore` has no effect on a tracked file, so in a retrofit where `AGENTS.md` (or `CLAUDE.md`) is already committed, writing a rule for it manufactures a false sense - Network accessline 140
**Lark/Feishu wiki provider:** - Detect: run `scripts/lark-preflight.sh` (read-only) → JSON `status` ∈ `cli_missing` / `not_authed` / `missing_wiki_scope` / `ok`, each with the exact next action in `next`. - Install (offer to run for the us - Network accessline 141
- Detect: run `scripts/lark-preflight.sh` (read-only) → JSON `status` ∈ `cli_missing` / `not_authed` / `missing_wiki_scope` / `ok`, each with the exact next action in `next`. - Install (offer to run for the user on confirmation): `npm insta - Network accessline 142
- Install (offer to run for the user on confirmation): `npm install -g @larksuite/cli && npx skills add larksuite/cli -y -g`, then `lark-cli config init` and `lark-cli auth login --recommend`. Docs: <https://github.com/larksuite/cli>. - Network accessline 145
**Notion provider:** - Detect: run `scripts/notion-preflight.sh --db <DATABASE_ID>` (read-only) → JSON `status` ∈ `not_authed` / `db_unshared` / `db_props_missing` / `db_prop_type_mismatch` / `net_error` / `ok`, each with the exact next act - Network accessline 146
- Detect: run `scripts/notion-preflight.sh --db <DATABASE_ID>` (read-only) → JSON `status` ∈ `not_authed` / `db_unshared` / `db_props_missing` / `db_prop_type_mismatch` / `net_error` / `ok`, each with the exact next action in `next`; type m - Network accessline 147
[Credential-related source omitted] - Access to secretsline 147
[Credential-related source omitted] - Network accessline 148
- Transport: direct REST via curl (the `ntn` CLI is unreliable behind an HTTPS proxy). See `graduation/notion.md`. - Network accessline 150
**Obsidian provider:** - Detect: run `scripts/obsidian-preflight.sh --vault "<vault name>" [--target "<folder>"] [--index "<folder>/INDEX.md"]` (read-only) → JSON `status` ∈ `cli_missing` / `app_unreachable` / `vault_unknown` / `vault_unrea - Network accessline 151
- Detect: run `scripts/obsidian-preflight.sh --vault "<vault name>" [--target "<folder>"] [--index "<folder>/INDEX.md"]` (read-only) → JSON `status` ∈ `cli_missing` / `app_unreachable` / `vault_unknown` / `vault_unreachable` / `ok`, each wi - Network accessline 152
- Install: unlike Lark/Notion, there is **no command the agent can run to install this** — the `obsidian` CLI ships inside the Obsidian.app bundle itself (1.12+) and is enabled with a GUI toggle: Settings → General → "Command line interface - Dangerous shell operationline 179
- **A pre-existing host file under `ignore` / `private_sync`.** When git tracks it (`git ls-files --error-unmatch <path>`), the import line goes out with its next commit. Say so before writing and let the user choose: append anyway; for Cod
references/provider-interface.md
- Network accessline 76
- **Obsidian** — the full four classes via the `obsidian` CLI (primitives confirmed present on CLI 1.12; not yet exercised at scale): structured `properties` / `property:read` / `base:query` (Bases saved views, `format=json`); tag `tag name - Network accessline 78
- **Lark wiki** — verified read path is tree traversal (`wiki nodes list`) plus INDEX-doc fetch (`docs +fetch`); suite-wide search APIs exist but are **unverified** for this flow — do not rely on them until tested in a real environment.
references/upgrade.md
- Dangerous shell operationline 104
- **Fix**: extend the ignore block to cover `<knowledge_dir>/`, `.cairn/`, and `AGENTS.md` / `CLAUDE.md` where Cairn authored them, and replace the block's comment with the neutral `# Local working files, not part of the project`. An ignore
scripts/.gitkeep
- Executable scriptline 1
Executable file
scripts/lark-preflight.sh
- Executable scriptline 1
#!/usr/bin/env bash - Network accessline 24
CLI="${LARK_CLI:-lark-cli}" DOCS="https://github.com/larksuite/cli" - Network accessline 25
DOCS="https://github.com/larksuite/cli" - Network accessline 30
emit() { # summary, status, next printf '%s\n' "$1" >&2 jq -nc \ - Network accessline 31
printf '%s\n' "$1" >&2 jq -nc \ --argjson installed "$INSTALLED" --arg version "$VERSION" \ - Network accessline 32
jq -nc \ - Network accessline 44
if ! command -v "$CLI" >/dev/null 2>&1; then emit "✗ lark-cli not installed." cli_missing \ "Install then re-run: npm install -g @larksuite/cli && npx skills add larksuite/cli -y -g ; then lark-cli config init && lark-cli auth login - - Network accessline 45
emit "✗ lark-cli not installed." cli_missing "Install then re-run: npm install -g @larksuite/cli && npx skills add larksuite/cli -y -g ; then lark-cli config init && lark-cli auth login --recommend. Docs: $DOCS" - Network accessline 46
"Install then re-run: npm install -g @larksuite/cli && npx skills add larksuite/cli -y -g ; then lark-cli config init && lark-cli auth login --recommend. Docs: $DOCS" - Network accessline 60
if [ "$AUTHED" != true ]; then emit "✗ lark-cli installed (${VERSION:-?}) but no authorized user session." not_authed \ "Run: $CLI auth login --recommend (or $CLI auth login --scope wiki:wiki for the wiki provider). Docs: $DOCS" - Network accessline 61
emit "✗ lark-cli installed (${VERSION:-?}) but no authorized user session." not_authed "Run: $CLI auth login --recommend (or $CLI auth login --scope wiki:wiki for the wiki provider). Docs: $DOCS" - Network accessline 62
"Run: $CLI auth login --recommend (or $CLI auth login --scope wiki:wiki for the wiki provider). Docs: $DOCS" - Network accessline 76
if [ "$SUB" = "missing_scope" ]; then emit "✗ Authorized as '${USER_NAME}' but user token cannot read wiki (missing scope)." missing_wiki_scope \ "Open the coarse 'wiki:wiki' scope for USER identity on the app in the developer console - Network accessline 77
emit "✗ Authorized as '${USER_NAME}' but user token cannot read wiki (missing scope)." missing_wiki_scope "Open the coarse 'wiki:wiki' scope for USER identity on the app in the developer console — find it by scope name, not by matching - Network accessline 78
"Open the coarse 'wiki:wiki' scope for USER identity on the app in the developer console — find it by scope name, not by matching a UI label, since the label text differs between consoles (on the Feishu (China) console it's '查看、评论、编辑和管理知识库' - Network accessline 82
emit "✗ Authorized as '${USER_NAME}' but wiki read probe failed (token/identity issue: ${SUB:-unknown})." not_authed \ "Re-authorize and retry: $CLI auth login --scope wiki:wiki. If it persists, $CLI auth logout then $CLI auth login --rec - Network accessline 83
"Re-authorize and retry: $CLI auth login --scope wiki:wiki. If it persists, $CLI auth logout then $CLI auth login --recommend. Docs: $DOCS"
scripts/lark-wiki-graduate.sh
- Executable scriptline 1
#!/usr/bin/env bash - Access to secretsline 114
[Credential-related source omitted] - Access to secretsline 115
[Credential-related source omitted] - Access to secretsline 125
[Credential-related source omitted] - Dangerous shell operationline 205
trap 'rm -f "$TMP_CONTENT"' EXIT - Access to secretsline 214
[Credential-related source omitted] - Access to secretsline 223
[Credential-related source omitted] - Access to secretsline 238
[Credential-related source omitted] - Access to secretsline 239
[Credential-related source omitted] - Access to secretsline 240
[Credential-related source omitted] - Network accessline 241
NODE_URL="$UPDATE_URL" else data="$(jq -nc --arg t "$TITLE" --arg p "$PARENT" \ - Network accessline 242
[Credential-related source omitted] - Network accessline 243
data="$(jq -nc --arg t "$TITLE" --arg p "$PARENT" \ - Access to secretsline 253
[Credential-related source omitted] - Access to secretsline 261
[Credential-related source omitted] - Access to secretsline 263
[Credential-related source omitted] - Access to secretsline 269
[Credential-related source omitted] - Access to secretsline 276
[Credential-related source omitted] - Network accessline 311
[Credential-related source omitted] - Access to secretsline 311
[Credential-related source omitted]
scripts/notion-graduate-batch.py
- Executable scriptline 1
#!/usr/bin/env python3 - Access to secretsline 20
[Credential-related source omitted] - Access to secretsline 30
[Credential-related source omitted] - Network accessline 38
[Credential-related source omitted] - Network accessline 39
url = f"https://api.notion.com/v1/{path}" - Network accessline 41
last = None for k in range(tries): req = urllib.request.Request(url, data=data, method=method, headers={ - Network accessline 42
[Credential-related source omitted] - Network accessline 43
req = urllib.request.Request(url, data=data, method=method, headers={ - Network accessline 45
"Content-Type": "application/json"}) try: return json.load(urllib.request.urlopen(req, timeout=30)) - Network accessline 46
try: return json.load(urllib.request.urlopen(req, timeout=30)) except urllib.error.HTTPError as e: - Network accessline 47
return json.load(urllib.request.urlopen(req, timeout=30)) - Access to secretsline 282
[Credential-related source omitted]
scripts/notion-graduate.sh
- Executable scriptline 1
#!/usr/bin/env bash - Network accessline 4
# Encodes the verified adapter constraints (see references/graduation/notion.md, # references/provider-interface.md, and cairn Notion Provider notes): # - Direct REST via curl (honors HTTPS_PROXY), NOT the `ntn` CLI (unreliable - Network accessline 5
# references/provider-interface.md, and cairn Notion Provider notes): # - Direct REST via curl (honors HTTPS_PROXY), NOT the `ntn` CLI (unreliable # behind a proxy: fetches an OpenAPI spec to resolve endpoints, does not - Network accessline 6
# - Direct REST via curl (honors HTTPS_PROXY), NOT the `ntn` CLI (unreliable - Access to secretsline 23
[Credential-related source omitted] - Network accessline 76
[ -z "$CONTENT_FILE" ] || [ -f "$CONTENT_FILE" ] || die "content file not found: $CONTENT_FILE" [ -z "$PROPS_JSON" ] || [ -f "$PROPS_JSON" ] || die "props-json not found: $PROPS_JSON" command -v curl >/dev/null 2>&1 || die "curl not found" - Network accessline 77
[ -z "$PROPS_JSON" ] || [ -f "$PROPS_JSON" ] || die "props-json not found: $PROPS_JSON" command -v curl >/dev/null 2>&1 || die "curl not found" command -v jq >/dev/null 2>&1 || die "jq not found" - Network accessline 78
command -v curl >/dev/null 2>&1 || die "curl not found" - Access to secretsline 88
[Credential-related source omitted] - Network accessline 109
fi else PROPS="$(jq -nc \ - Network accessline 110
else PROPS="$(jq -nc \ --arg title "$TITLE" --arg type "$TYPE" --arg gfrom "$GFROM" \ - Network accessline 111
PROPS="$(jq -nc \ - Network accessline 173
PAYLOAD_FILE="$(mktemp -t notion-grad.XXXXXX)" trap 'rm -f "$PAYLOAD_FILE"' EXIT jq -nc --arg db "$DB" --argjson props "$PROPS" --argjson children "$CHILDREN" \ - Dangerous shell operationline 174
trap 'rm -f "$PAYLOAD_FILE"' EXIT - Network accessline 174
trap 'rm -f "$PAYLOAD_FILE"' EXIT jq -nc --arg db "$DB" --argjson props "$PROPS" --argjson children "$CHILDREN" \ '{parent:{database_id:$db}, properties:$props, children:$children}' > "$PAYLOAD_FILE" - Network accessline 175
jq -nc --arg db "$DB" --argjson props "$PROPS" --argjson children "$CHILDREN" \ - Network accessline 178
if [ "$DRY_RUN" -eq 1 ]; then if [ -n "$PAGE_ID" ]; then echo "DRY-RUN: PATCH https://api.notion.com/v1/pages/$PAGE_ID properties; DELETE existing children; PATCH replacement children (Notion-Version $NV)" >&2 - Network accessline 179
if [ -n "$PAGE_ID" ]; then echo "DRY-RUN: PATCH https://api.notion.com/v1/pages/$PAGE_ID properties; DELETE existing children; PATCH replacement children (Notion-Version $NV)" >&2 else - Network accessline 180
echo "DRY-RUN: PATCH https://api.notion.com/v1/pages/$PAGE_ID properties; DELETE existing children; PATCH replacement children (Notion-Version $NV)" >&2 - Network accessline 181
else echo "DRY-RUN: POST https://api.notion.com/v1/pages (Notion-Version $NV)" >&2 fi - Network accessline 182
echo "DRY-RUN: POST https://api.notion.com/v1/pages (Notion-Version $NV)" >&2 - Network accessline 185
echo " children: $(printf '%s' "$CHILDREN" | jq 'length') blocks" >&2 echo " child types: $(printf '%s' "$CHILDREN" | jq -c '[.[].type]')" >&2 jq -nc --arg id "${PAGE_ID:-<dry-run>}" --arg t "$TITLE" '{id:$id, url:"<dry-run>", title - Network accessline 186
echo " child types: $(printf '%s' "$CHILDREN" | jq -c '[.[].type]')" >&2 jq -nc --arg id "${PAGE_ID:-<dry-run>}" --arg t "$TITLE" '{id:$id, url:"<dry-run>", title:$t}' exit 0 - Network accessline 187
jq -nc --arg id "${PAGE_ID:-<dry-run>}" --arg t "$TITLE" '{id:$id, url:"<dry-run>", title:$t}' - Network accessline 195
attempt=$((attempt + 1)) if [ -n "$bf" ]; then resp="$(curl -sS -X "$method" "https://api.notion.com/v1/$path" \ - Network accessline 196
[Credential-related source omitted] - Network accessline 197
[Credential-related source omitted] - Access to secretsline 197
[Credential-related source omitted] - Access to secretsline 198
[Credential-related source omitted] - Network accessline 199
-H "Content-Type: application/json" --data @"$bf" 2>/dev/null)"; rc=$? else resp="$(curl -sS -X "$method" "https://api.notion.com/v1/$path" \ - Network accessline 200
[Credential-related source omitted] - Network accessline 201
[Credential-related source omitted] - Access to secretsline 201
[Credential-related source omitted] - Access to secretsline 202
[Credential-related source omitted] - Network accessline 211
while [ "$attempt" -lt "$max" ]; do attempt=$((attempt + 1)) resp="$(curl -sS "https://api.notion.com/v1/$path" \ - Network accessline 212
[Credential-related source omitted] - Network accessline 213
[Credential-related source omitted] - Access to secretsline 213
[Credential-related source omitted] - Access to secretsline 214
[Credential-related source omitted] - Network accessline 223
CHILDREN_FILE="$(mktemp -t notion-children.XXXXXX)" trap 'rm -f "$PAYLOAD_FILE" "$PROPERTIES_FILE" "$CHILDREN_FILE"' EXIT jq -nc --argjson props "$PROPS" '{properties:$props}' > "$PROPERTIES_FILE" - Dangerous shell operationline 224
trap 'rm -f "$PAYLOAD_FILE" "$PROPERTIES_FILE" "$CHILDREN_FILE"' EXIT - Network accessline 224
trap 'rm -f "$PAYLOAD_FILE" "$PROPERTIES_FILE" "$CHILDREN_FILE"' EXIT jq -nc --argjson props "$PROPS" '{properties:$props}' > "$PROPERTIES_FILE" jq -nc --argjson children "$CHILDREN" '{children:$children}' > "$CHILDREN_FILE" - Network accessline 225
jq -nc --argjson props "$PROPS" '{properties:$props}' > "$PROPERTIES_FILE" - Network accessline 226
jq -nc --argjson children "$CHILDREN" '{children:$children}' > "$CHILDREN_FILE" - Dangerous shell operationline 232
trap 'rm -f "$PAYLOAD_FILE" "$PROPERTIES_FILE" "$CHILDREN_FILE" "$BLOCK_IDS_FILE"' EXIT - Network accessline 282
jq -nc --arg id "$PAGE_ID" --arg url "$PAGE_URL" '{id:$id, url:$url}'
scripts/notion-init-db.sh
- Executable scriptline 1
#!/usr/bin/env bash - Network accessline 7
# the notes) — there is no separate INDEX page. # # Direct REST via curl (honors HTTPS_PROXY) + retry; pinned Notion-Version. - Network accessline 8
# # Direct REST via curl (honors HTTPS_PROXY) + retry; pinned Notion-Version. # The parent page must be shared with the integration first. - Network accessline 9
# Direct REST via curl (honors HTTPS_PROXY) + retry; pinned Notion-Version. - Access to secretsline 12
[Credential-related source omitted] - Network accessline 37
[ -n "$PARENT" ] || die "--parent-page-id is required (a page shared with the integration)" [ -n "$TITLE" ] || die "--title is required (the knowledge-base database name, e.g. \"<Project Name> Knowledge Base\")" command -v curl >/dev/null 2 - Network accessline 38
[ -n "$TITLE" ] || die "--title is required (the knowledge-base database name, e.g. \"<Project Name> Knowledge Base\")" command -v curl >/dev/null 2>&1 || die "curl not found" command -v jq >/dev/null 2>&1 || die "jq not found" - Network accessline 39
command -v curl >/dev/null 2>&1 || die "curl not found" - Access to secretsline 45
[Credential-related source omitted] - Network accessline 48
PAYLOAD_FILE="$(mktemp -t notion-initdb.XXXXXX)" trap 'rm -f "$PAYLOAD_FILE"' EXIT jq -nc --arg parent "$PARENT" --arg title "$TITLE" --arg type "$TYPE" '{ - Dangerous shell operationline 49
trap 'rm -f "$PAYLOAD_FILE"' EXIT - Network accessline 49
trap 'rm -f "$PAYLOAD_FILE"' EXIT jq -nc --arg parent "$PARENT" --arg title "$TITLE" --arg type "$TYPE" '{ parent: {type:"page_id", page_id:$parent}, - Network accessline 50
jq -nc --arg parent "$PARENT" --arg title "$TITLE" --arg type "$TYPE" '{ - Network accessline 69
if [ "$DRY_RUN" -eq 1 ]; then echo "DRY-RUN: POST https://api.notion.com/v1/databases (Notion-Version $NV)" >&2 - Network accessline 70
echo "DRY-RUN: POST https://api.notion.com/v1/databases (Notion-Version $NV)" >&2 - Network accessline 71
echo " parent page: $PARENT title: $TITLE" >&2 echo " properties: $(jq -c '.properties | keys' "$PAYLOAD_FILE")" >&2 jq -nc '{database_id:"<dry-run>", url:"<dry-run>"}' - Network accessline 72
echo " properties: $(jq -c '.properties | keys' "$PAYLOAD_FILE")" >&2 jq -nc '{database_id:"<dry-run>", url:"<dry-run>"}' exit 0 - Network accessline 73
jq -nc '{database_id:"<dry-run>", url:"<dry-run>"}' - Network accessline 79
while [ "$attempt" -lt "$max" ]; do attempt=$((attempt + 1)) RESP="$(curl -sS -X POST "https://api.notion.com/v1/databases" \ - Network accessline 80
[Credential-related source omitted] - Network accessline 81
[Credential-related source omitted] - Access to secretsline 81
[Credential-related source omitted] - Access to secretsline 82
[Credential-related source omitted] - Network accessline 99
jq -nc --arg id "$DBID" --arg url "$URL" '{database_id:$id, url:$url}'
scripts/notion-preflight.sh
- Executable scriptline 1
#!/usr/bin/env bash - Network accessline 4
# Run this BEFORE attempting any Notion graduation. It diagnoses what the # notion-graduate adapter assumes and a user must set up out-of-band: # 1. curl + jq are available - Network accessline 5
# notion-graduate adapter assumes and a user must set up out-of-band: # 1. curl + jq are available # 2. NOTION_API_TOKEN is set (an internal-integration token; keep it in .env) - Network accessline 6
# 1. curl + jq are available - Network accessline 42
emit() { # summary status next printf '%s\n' "$1" >&2 jq -nc \ - Network accessline 43
printf '%s\n' "$1" >&2 jq -nc \ --argjson deps "$INSTALLED" --argjson token "$TOKEN_SET" \ - Network accessline 44
jq -nc \ - Network accessline 57
while [ "$attempt" -lt "$max" ]; do attempt=$((attempt + 1)) resp="$(curl -sS "https://api.notion.com/v1/$path" \ - Network accessline 58
[Credential-related source omitted] - Network accessline 59
[Credential-related source omitted] - Access to secretsline 59
[Credential-related source omitted] - Access to secretsline 60
[Credential-related source omitted] - Network accessline 69
command -v curl >/dev/null 2>&1 || { echo "error: curl not found" >&2; exit 1; } - Network accessline 74
[Credential-related source omitted] - Access to secretsline 74
[Credential-related source omitted] - Network accessline 75
[Credential-related source omitted] - Access to secretsline 75
[Credential-related source omitted] - Network accessline 76
[Credential-related source omitted] - Access to secretsline 76
[Credential-related source omitted] - Network accessline 86
BODY="$(napi_get "databases/$DB")" || { emit "✗ Network give-up reaching Notion API (proxy/SSL flakiness)." net_error \ "Check HTTPS_PROXY reachability and retry; curl honors the proxy env."; exit 1; } - Network accessline 87
"Check HTTPS_PROXY reachability and retry; curl honors the proxy env."; exit 1; }
scripts/obsidian-graduate.sh
- Executable scriptline 1
#!/usr/bin/env bash - Network accessline 205
printf '%s\n' "$FRONTMATTER" | sed 's/^/ /' >&2 [ -n "$INDEX" ] && echo "DRY-RUN: would append a WikiLink line to $VAULT_PATH/$INDEX" >&2 jq -nc --arg p "$REL_PATH" '{path:$p, obsidian_url:"<dry-run>"}' - Network accessline 206
[ -n "$INDEX" ] && echo "DRY-RUN: would append a WikiLink line to $VAULT_PATH/$INDEX" >&2 jq -nc --arg p "$REL_PATH" '{path:$p, obsidian_url:"<dry-run>"}' exit 0 - Network accessline 207
jq -nc --arg p "$REL_PATH" '{path:$p, obsidian_url:"<dry-run>"}' - Dangerous shell operationline 214
trap 'rm -f "$TMP_FILE"' EXIT - Network accessline 247
ENC_VAULT="$(jq -rn --arg v "$VAULT" '$v|@uri')" ENC_PATH="$(jq -rn --arg p "$REL_PATH" '$p|@uri')" jq -nc --arg p "$REL_PATH" --arg url "obsidian://open?vault=$ENC_VAULT&file=$ENC_PATH" \ - Network accessline 248
ENC_PATH="$(jq -rn --arg p "$REL_PATH" '$p|@uri')" jq -nc --arg p "$REL_PATH" --arg url "obsidian://open?vault=$ENC_VAULT&file=$ENC_PATH" \ '{path:$p, obsidian_url:$url}' - Network accessline 249
jq -nc --arg p "$REL_PATH" --arg url "obsidian://open?vault=$ENC_VAULT&file=$ENC_PATH" \
scripts/obsidian-preflight.sh
- Executable scriptline 1
#!/usr/bin/env bash - Network accessline 45
CLI="${OBSIDIAN_CLI:-obsidian}" DOCS="https://help.obsidian.md/cli" - Network accessline 46
DOCS="https://help.obsidian.md/cli" - Network accessline 64
emit() { # summary status next printf '%s\n' "$1" >&2 jq -nc \ - Network accessline 65
printf '%s\n' "$1" >&2 jq -nc \ --argjson installed "$INSTALLED" --argjson app_ok "$APP_OK" \ - Network accessline 66
jq -nc \ - Network accessline 78
if ! command -v "$CLI" >/dev/null 2>&1; then emit "✗ obsidian CLI not found on PATH." cli_missing \ "In Obsidian: Settings → General → \"Command line interface\", turn it on. This ships inside the app itself; it's a one-click GUI sett - Network accessline 79
emit "✗ obsidian CLI not found on PATH." cli_missing "In Obsidian: Settings → General → \"Command line interface\", turn it on. This ships inside the app itself; it's a one-click GUI setting the agent cannot toggle for you. See $DOCS." - Network accessline 80
"In Obsidian: Settings → General → \"Command line interface\", turn it on. This ships inside the app itself; it's a one-click GUI setting the agent cannot toggle for you. See $DOCS."
tests/test_note_type.py
- Executable scriptline 1
Executable file - Access to secretsline 28
[Credential-related source omitted] - Access to secretsline 32
[Credential-related source omitted] - Network accessline 34
[Credential-related source omitted] - Network accessline 35
[Credential-related source omitted] - Network accessline 36
[Credential-related source omitted] - Network accessline 48
state=json.loads(statefile.read_text()) if statefile.exists() else {'properties':{}} if method=='POST' and url.endswith('/databases'): print(json.dumps({'object':'database','id':'db','url':'https://fake.test/db'})) - Network accessline 49
if method=='POST' and url.endswith('/databases'): print(json.dumps({'object':'database','id':'db','url':'https://fake.test/db'})) elif method in ('POST','PATCH') and ('/pages' in url): - Network accessline 50
print(json.dumps({'object':'database','id':'db','url':'https://fake.test/db'})) - Network accessline 51
elif method in ('POST','PATCH') and ('/pages' in url): state['properties'].update(payload['properties']); statefile.write_text(json.dumps(state)) print(json.dumps({'object':'page','id':'page','url':'https://fake.test/page'}) - Network accessline 52
state['properties'].update(payload['properties']); statefile.write_text(json.dumps(state)) print(json.dumps({'object':'page','id':'page','url':'https://fake.test/page'})) elif method=='GET' and '/pages/' in url: - Network accessline 53
print(json.dumps({'object':'page','id':'page','url':'https://fake.test/page'})) - Network accessline 56
print(json.dumps({'object':'page',**state})) elif '/blocks/' in url: print('{"results":[],"has_more":false}') else: raise SystemExit('unexpected curl call') - Network accessline 57
elif '/blocks/' in url: print('{"results":[],"has_more":false}') else: raise SystemExit('unexpected curl call') ''' - Network accessline 58
else: raise SystemExit('unexpected curl call') - Access to secretsline 64
[Credential-related source omitted] - Network accessline 130
assert fm(target)['type'] == note_type assert fm(target)['graduated_by'] == ['Alice', 'Bob'] result = run_adapter('lark-wiki-graduate.sh', common + ['--space-id', 'space', '--identity', 'bot', '--update-node-token', 'node', '--updat - Network accessline 131
assert fm(target)['graduated_by'] == ['Alice', 'Bob'] result = run_adapter('lark-wiki-graduate.sh', common + ['--space-id', 'space', '--identity', 'bot', '--update-node-token', 'node', '--update-obj-token', 'doc', '--update-url', 'https - Network accessline 132
result = run_adapter('lark-wiki-graduate.sh', common + ['--space-id', 'space', '--identity', 'bot', '--update-node-token', 'node', '--update-obj-token', 'doc', '--update-url', 'https://fake.test/wiki/node'], env) - Network accessline 153
assert target.read_bytes() == before (temp / 'calls.jsonl').unlink() result = run_adapter('lark-wiki-graduate.sh', ['--title', 'Sample', '--identity', 'bot', '--graduated-by', 'Bob', '--update-node-token', 'node', '--update-obj-toke - Network accessline 154
(temp / 'calls.jsonl').unlink() result = run_adapter('lark-wiki-graduate.sh', ['--title', 'Sample', '--identity', 'bot', '--graduated-by', 'Bob', '--update-node-token', 'node', '--update-obj-token', 'doc', '--update-url', 'https://fake. - Network accessline 155
result = run_adapter('lark-wiki-graduate.sh', ['--title', 'Sample', '--identity', 'bot', '--graduated-by', 'Bob', '--update-node-token', 'node', '--update-obj-token', 'doc', '--update-url', 'https://fake.test/wiki/node'], env) - Network accessline 168
assert fm(target)['type'] == 'project_insight' (temp / 'lark.md').write_text('---\ntype: knowledge_note\n---\nOld body\n') result = run_adapter('lark-wiki-graduate.sh', common + ['--space-id', 'space', '--identity', 'bot', '--update - Network accessline 169
(temp / 'lark.md').write_text('---\ntype: knowledge_note\n---\nOld body\n') result = run_adapter('lark-wiki-graduate.sh', common + ['--space-id', 'space', '--identity', 'bot', '--update-node-token', 'node', '--update-obj-token', 'doc', - Network accessline 170
result = run_adapter('lark-wiki-graduate.sh', common + ['--space-id', 'space', '--identity', 'bot', '--update-node-token', 'node', '--update-obj-token', 'doc', '--update-url', 'https://fake.test/wiki/node'], env)
tests/test_notion_graduate_batch.py
- Executable scriptline 1
Executable file
How the signals fit together
Facts from a static read of the files at the pinned commit. They describe what the code does, not why.
Some files could not be read; the facts below still hold.
Declared and executed: 6 facts
- Contacts api.notion.com, which SKILL.md, the README and the plugin manifest do not mentionscripts/notion-graduate-batch.py:39High confidence
- Contacts api.notion.com, which SKILL.md, the README and the plugin manifest do not mentionscripts/notion-graduate.sh:180High confidence
- Contacts api.notion.com, which SKILL.md, the README and the plugin manifest do not mentionscripts/notion-init-db.sh:70High confidence
- Contacts api.notion.com, which SKILL.md, the README and the plugin manifest do not mentionscripts/notion-preflight.sh:59High confidence
- Contacts www.notion.so, which SKILL.md, the README and the plugin manifest do not mentionscripts/notion-preflight.sh:76High confidence
- Contacts help.obsidian.md, which SKILL.md, the README and the plugin manifest do not mentionscripts/obsidian-preflight.sh:46High confidence
Signal confidence: 228 facts
- Network access in prose of documentationREADME.md:7Low confidence
- Network access in prose of documentationREADME.md:9Low confidence
- Network access in code of documentationREADME.md:43Low confidence
- Network access in code of documentationREADME.md:49Low confidence
- Network access in prose of documentationREADME.md:54Low confidence
- Network access in prose of documentationREADME.md:58Low confidence
- Network access in prose of documentationREADME.md:95Low confidence
- Network access in prose of documentationREADME.md:113Low confidence
- Network access in prose of documentationREADME.md:147Low confidence
- Network access in prose of documentationREADME.md:148Low confidence
- Network access in prose of documentationREADME.md:149Low confidence
- Network access in prose of documentationREADME.md:150Low confidence
- Network access in prose of documentationREADME.md:152Low confidence
- Network access in prose of documentationREADME.zh-CN.md:7Low confidence
- Network access in prose of documentationREADME.zh-CN.md:9Low confidence
- Network access in code of documentationREADME.zh-CN.md:43Low confidence
- Network access in code of documentationREADME.zh-CN.md:49Low confidence
- Network access in prose of documentationREADME.zh-CN.md:54Low confidence
- Network access in prose of documentationREADME.zh-CN.md:58Low confidence
- Network access in prose of documentationREADME.zh-CN.md:95Low confidence
- Network access in prose of documentationREADME.zh-CN.md:113Low confidence
- Network access in prose of documentationREADME.zh-CN.md:147Low confidence
- Network access in prose of documentationREADME.zh-CN.md:148Low confidence
- Network access in prose of documentationREADME.zh-CN.md:149Low confidence
- Network access in prose of documentationREADME.zh-CN.md:150Low confidence
- Network access in prose of documentationREADME.zh-CN.md:152Low confidence
- Network access in prose of documentationreferences/graduation/notion.md:10Low confidence
- Network access in prose of documentationreferences/graduation/notion.md:11Low confidence
- Dangerous shell operation in prose of documentationreferences/init.md:57Low confidence
- Network access in prose of documentationreferences/init.md:140Low confidence
- Network access in prose of documentationreferences/init.md:141Low confidence
- Network access in prose of documentationreferences/init.md:142Low confidence
- Network access in prose of documentationreferences/init.md:145Low confidence
- Network access in prose of documentationreferences/init.md:146Low confidence
- Network access in prose of documentationreferences/init.md:147Low confidence
- Access to secrets in prose of documentation: a variable, placeholder or call, not a stored valuereferences/init.md:147Low confidence
- Network access in prose of documentationreferences/init.md:148Low confidence
- Network access in prose of documentationreferences/init.md:150Low confidence
- Network access in prose of documentationreferences/init.md:151Low confidence
- Network access in prose of documentationreferences/init.md:152Low confidence
- Dangerous shell operation in prose of documentationreferences/init.md:179Low confidence
- Network access in prose of documentationreferences/provider-interface.md:76Low confidence
- Network access in prose of documentationreferences/provider-interface.md:78Low confidence
- Dangerous shell operation in prose of documentationreferences/upgrade.md:104Low confidence
- Executable script in code of a file that runsscripts/.gitkeep:1High confidence
- Executable script in code of a file that runsscripts/lark-preflight.sh:1High confidence
- Network access in code of a file that runsscripts/lark-preflight.sh:24High confidence
- Network access in code of a file that runsscripts/lark-preflight.sh:25High confidence
- Network access in code of a file that runsscripts/lark-preflight.sh:30High confidence
- Network access in code of a file that runsscripts/lark-preflight.sh:31High confidence
and 178 more
Works with
| Agent | Status | Evidence | Install to |
|---|---|---|---|
| Claude Code | Compatible | Standard SKILL.md SKILL.md | .claude/skills/<skill-name>/ |
| Codex | Native | Manifest assets/templates/AGENTS.md | .agents/skills/<skill-name>/ |
| Cursor | Compatible | Standard SKILL.md SKILL.md | .cursor/skills/<skill-name>/ |
| Gemini CLI | Compatible | Standard SKILL.md SKILL.md | .gemini/skills/<skill-name>/ |
| GitHub Copilot | Compatible | Standard SKILL.md SKILL.md | .github/skills/<skill-name>/ |
| OpenCode | Compatible | Standard SKILL.md SKILL.md | .opencode/skills/<skill-name>/ |
- Native The repository ships a manifest, folder or frontmatter field for this agent.
- Compatible A standard SKILL.md that this agent can read.
- Unknown No evidence either way.
Derived automatically from paths, manifests and frontmatter. Not tested on each agent.
