Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

docs: add upgrade guide and update quick start for multi-agent (#36)

Brenno Ferrari681e926d852c
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 91e33e8..7534fb7 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -36,6 +36,10 @@ jobs:
if [[ ! "$VERSION" =~ ^v ]]; then
VERSION="v$VERSION"
fi
+ # Normalize bare major (v4 → v4.0) or major.minor (v4.0 stays v4.0)
+ if [[ "$VERSION" =~ ^v[0-9]+$ ]]; then
+ VERSION="${VERSION}.0"
+ fi
else
VERSION="${GITHUB_REF#refs/tags/}"
fi
@@ -69,16 +73,19 @@ jobs:
cat > /tmp/release_body.md <<'HEADER'
## Quick Start
- **Requirements:** [Obsidian](https://obsidian.md), [Claude Code](https://claude.ai/code), [Python 3.8+](https://python.org/downloads)
+ **Requirements:** [Obsidian](https://obsidian.md), [Python 3.8+](https://python.org/downloads), and one of: [Claude Code](https://claude.ai/code) · [Codex CLI](https://github.com/openai/codex) · [Gemini CLI](https://github.com/google-gemini/gemini-cli)
```bash
git clone https://github.com/breferrari/obsidian-mind.git
cd obsidian-mind
- npm install -g @tobilu/qmd # optional: semantic search
- qmd index && qmd embed # build search index
+ npm install -g @tobilu/qmd && qmd index && qmd embed # optional: semantic search
```
- Or download the vault zip below and extract it into your Obsidian vaults folder. Open it in Claude Code and run `/om-standup`.
+ Open the folder as an Obsidian vault, then run `claude`, `codex`, or `gemini` in the directory and type `/om-standup` (or `om-standup` in Codex).
+
+ Or download the vault zip below and extract it into your Obsidian vaults folder.
+
+ **Already using obsidian-mind?** Just tell your agent: `Update this vault to the latest obsidian-mind from https://github.com/breferrari/obsidian-mind`
HEADER
# Strip leading whitespace from heredoc
diff --git a/README.ja.md b/README.ja.md
index 70cfee2..0845f88 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -99,7 +99,7 @@ Decision: defer Redis migration. Win: Sarah praised the auth architecture.
1. このリポジトリをクローン(または**GitHubテンプレート**として使用)
2. フォルダを**Obsidianボールト**として開く
3. 設定 → 一般で**Obsidian CLI**を有効化(Obsidian 1.12以上が必要)
-4. ボールトディレクトリで**`claude`**を実行
+4. ボールトディレクトリでエージェントを実行:**`claude`**、**`codex`**、または**`gemini`**
5. **`brain/North Star.md`**に目標を記入 — これがすべてのセッションの基盤になります
6. 仕事について話し始める
@@ -386,21 +386,56 @@ YAMLフロントマター付きテンプレート。段階的開示のための`
## 🔄 アップグレード
+### エージェントに頼む
+
+一番簡単な方法 — エージェントに伝えるだけ:
+
+```
+このボールトを最新のobsidian-mindに更新して https://github.com/breferrari/obsidian-mind
+```
+
+エージェントが最新の変更を取得し、コンフリクトを解消し、インフラファイルを更新します。Claude Code、Codex CLI、Gemini CLIで動作します。
+
+### 既存クローンの更新
+
+リポジトリを直接クローンした場合:
+
+```bash
+cd your-vault
+git pull origin main
+```
+
+新しいファイル(`AGENTS.md`、`GEMINI.md`、`.codex/`、`.gemini/`)が自動的に追加され、フックスクリプトも更新されます。
+
+### フォークの更新
+
+リポジトリをフォークした場合:
+
+```bash
+git remote add upstream https://github.com/breferrari/obsidian-mind.git
+git fetch upstream
+git merge upstream/main
+```
+
+カスタマイズしたファイル(通常は`CLAUDE.md`、`brain/`ノート)のコンフリクトを解消してください。インフラファイル(`.claude/scripts/`、`.codex/`、`.gemini/`)はクリーンにマージされます。
+
+### 古いボールトからの移行
+
obsidian-mindの古いバージョン(または任意のObsidianボールト)をお使いですか?`/om-vault-upgrade`コマンドでコンテンツを最新テンプレートに移行できます:
```bash
# 1. 最新のobsidian-mindをクローン
git clone https://github.com/breferrari/obsidian-mind.git ~/new-vault
-# 2. Claude Codeで開く
-cd ~/new-vault && claude
+# 2. エージェントで開く
+cd ~/new-vault && claude # または codex、gemini
# 3. 古いボールトを指定してアップグレードを実行
/om-vault-upgrade ~/my-old-vault
```
エージェントが以下を行います:
-1. **検出** — ボールトのバージョンを特定(v1〜v3.2、またはobsidian-mind以外のボールトとして識別)
+1. **検出** — ボールトのバージョンを特定(v1〜v3.x、またはobsidian-mind以外のボールトとして識別)
2. **棚卸し** — すべてのファイルを分類(ユーザーコンテンツ、スキャフォールド、インフラ、未分類)
3. **移行プランの提示** — コピー、変換、スキップされるものを正確に確認できます
4. **承認後に実行** — フロントマターの変換、ウィキリンクの修正、インデックスの再構築
diff --git a/README.ko.md b/README.ko.md
index ee2ce6b..0b8b321 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -99,7 +99,7 @@ You: "wrap up"
1. 이 저장소를 클론하거나 **GitHub 템플릿**으로 사용하세요
2. 폴더를 **Obsidian 볼트**로 엽니다
3. 설정 → 일반에서 **Obsidian CLI**를 활성화합니다 (Obsidian 1.12+ 필요)
-4. 볼트 디렉토리에서 **`claude`**를 실행합니다
+4. 볼트 디렉토리에서 에이전트를 실행합니다: **`claude`**, **`codex`**, 또는 **`gemini`**
5. **`brain/North Star.md`**에 목표를 작성합니다 — 이것이 모든 세션의 기준이 됩니다
6. 업무에 대해 이야기를 시작하세요
@@ -386,21 +386,56 @@ YAML 프론트매터가 포함된 템플릿으로, 각각 점진적 공개를
## 🔄 업그레이드
+### 에이전트에게 요청하기
+
+가장 간단한 방법 — 에이전트에게 말하세요:
+
+```
+이 볼트를 최신 obsidian-mind로 업데이트해줘 https://github.com/breferrari/obsidian-mind
+```
+
+에이전트가 최신 변경사항을 가져오고, 충돌을 해결하고, 인프라 파일을 업데이트합니다. Claude Code, Codex CLI, Gemini CLI 모두에서 작동합니다.
+
+### 기존 클론 업데이트
+
+리포지토리를 직접 클론한 경우:
+
+```bash
+cd your-vault
+git pull origin main
+```
+
+새 파일(`AGENTS.md`, `GEMINI.md`, `.codex/`, `.gemini/`)이 자동으로 추가되고 훅 스크립트도 업데이트됩니다.
+
+### 포크 업데이트
+
+리포지토리를 포크한 경우:
+
+```bash
+git remote add upstream https://github.com/breferrari/obsidian-mind.git
+git fetch upstream
+git merge upstream/main
+```
+
+커스터마이징한 파일(일반적으로 `CLAUDE.md`, `brain/` 노트)의 충돌을 해결하세요. 인프라 파일(`.claude/scripts/`, `.codex/`, `.gemini/`)은 깔끔하게 병합됩니다.
+
+### 이전 볼트에서 마이그레이션
+
이전 버전의 obsidian-mind(또는 기존 Obsidian 볼트)를 사용 중이신가요? `/om-vault-upgrade` 명령어가 최신 템플릿으로 콘텐츠를 마이그레이션합니다:
```bash
-# 1. Clone the latest obsidian-mind
+# 1. 최신 obsidian-mind 클론
git clone https://github.com/breferrari/obsidian-mind.git ~/new-vault
-# 2. Open it in Claude Code
-cd ~/new-vault && claude
+# 2. 에이전트로 열기
+cd ~/new-vault && claude # 또는 codex, gemini
-# 3. Run the upgrade pointing to your old vault
+# 3. 이전 볼트를 지정하여 업그레이드 실행
/om-vault-upgrade ~/my-old-vault
```
에이전트가 수행하는 작업:
-1. **감지** — 볼트 버전 확인 (v1–v3.2, 또는 obsidian-mind가 아닌 볼트 식별)
+1. **감지** — 볼트 버전 확인 (v1–v3.x, 또는 obsidian-mind가 아닌 볼트 식별)
2. **인벤토리** — 모든 파일을 사용자 콘텐츠, 스캐폴드, 인프라, 미분류로 분류
3. **마이그레이션 계획 제시** — 복사, 변환, 건너뛸 항목을 정확히 보여줌
4. **승인 후 실행** — 프론트매터 변환, 위키링크 수정, 인덱스 재구축
diff --git a/README.md b/README.md
index c8b611a..c1fedb9 100644
--- a/README.md
+++ b/README.md
@@ -98,7 +98,7 @@ You: "wrap up"
1. Clone this repo (or use it as a **GitHub template**)
2. Open the folder as an **Obsidian vault**
3. Enable the **Obsidian CLI** in Settings → General (requires Obsidian 1.12+)
-4. Run **`claude`** in the vault directory
+4. Run your agent in the vault directory: **`claude`**, **`codex`**, or **`gemini`**
5. Fill in **`brain/North Star.md`** with your goals — this grounds every session
6. Start talking about work
@@ -385,21 +385,56 @@ This is a starting point. Adapt it to how you work:
## 🔄 Upgrading
-Already using an older version of obsidian-mind (or any Obsidian vault)? The `/om-vault-upgrade` command migrates your content into the latest template:
+### Ask your agent
+
+The easiest way — just tell your agent:
+
+```
+Update this vault to the latest obsidian-mind from https://github.com/breferrari/obsidian-mind
+```
+
+The agent will pull the latest changes, resolve conflicts, and update infrastructure files. Works with Claude Code, Codex CLI, or Gemini CLI.
+
+### Updating an existing clone
+
+If you cloned the repo directly:
+
+```bash
+cd your-vault
+git pull origin main
+```
+
+New files (`AGENTS.md`, `GEMINI.md`, `.codex/`, `.gemini/`) appear automatically and hook scripts are updated in place.
+
+### Updating a fork
+
+If you forked the repo:
+
+```bash
+git remote add upstream https://github.com/breferrari/obsidian-mind.git
+git fetch upstream
+git merge upstream/main
+```
+
+Resolve any conflicts in files you customized (typically `CLAUDE.md`, `brain/` notes). Infrastructure files (`.claude/scripts/`, `.codex/`, `.gemini/`) should merge cleanly.
+
+### Migrating from an older vault
+
+Using an older version of obsidian-mind (or any Obsidian vault)? The `/om-vault-upgrade` command migrates your content into the latest template:
```bash
# 1. Clone the latest obsidian-mind
git clone https://github.com/breferrari/obsidian-mind.git ~/new-vault
-# 2. Open it in Claude Code
-cd ~/new-vault && claude
+# 2. Open it in your agent
+cd ~/new-vault && claude # or codex, or gemini
# 3. Run the upgrade pointing to your old vault
/om-vault-upgrade ~/my-old-vault
```
The agent will:
-1. **Detect** your vault version (v1–v3.2, or identify it as a non-obsidian-mind vault)
+1. **Detect** your vault version (v1–v3.x, or identify it as a non-obsidian-mind vault)
2. **Inventory** every file — classify as user content, scaffold, infrastructure, or uncategorized
3. **Present a migration plan** — you see exactly what will be copied, transformed, and skipped
4. **Execute** after your approval — transforms frontmatter, fixes wikilinks, rebuilds indexes
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 5cb80da..d7737f4 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -99,7 +99,7 @@ Decision: defer Redis migration. Win: Sarah praised the auth architecture.
1. 克隆此仓库(或使用它作为 **GitHub 模板**)
2. 将文件夹作为 **Obsidian 仓库** 打开
3. 在 设置 → 通用 中启用 **Obsidian CLI**(需要 Obsidian 1.12+)
-4. 在仓库目录中运行 **`claude`**
+4. 在仓库目录中运行你的 Agent:**`claude`**、**`codex`** 或 **`gemini`**
5. 在 **`brain/North Star.md`** 中填写你的目标——这将为每次会话定下基调
6. 开始谈论工作
@@ -386,21 +386,56 @@ templates/ 带有 YAML frontmatter 的 Obsidian 模板
## 🔄 升级
+### 让 Agent 帮你更新
+
+最简单的方法 — 直接告诉你的 Agent:
+
+```
+把这个 vault 更新到最新的 obsidian-mind https://github.com/breferrari/obsidian-mind
+```
+
+Agent 会拉取最新更改、解决冲突并更新基础设施文件。Claude Code、Codex CLI 和 Gemini CLI 均可使用。
+
+### 更新已有克隆
+
+如果你直接克隆了仓库:
+
+```bash
+cd your-vault
+git pull origin main
+```
+
+新文件(`AGENTS.md`、`GEMINI.md`、`.codex/`、`.gemini/`)会自动出现,钩子脚本也会就地更新。
+
+### 更新 Fork
+
+如果你 Fork 了仓库:
+
+```bash
+git remote add upstream https://github.com/breferrari/obsidian-mind.git
+git fetch upstream
+git merge upstream/main
+```
+
+解决你自定义过的文件的冲突(通常是 `CLAUDE.md`、`brain/` 笔记)。基础设施文件(`.claude/scripts/`、`.codex/`、`.gemini/`)应该可以干净合并。
+
+### 从旧仓库迁移
+
已经在使用旧版本的 obsidian-mind(或其他 Obsidian 仓库)?`/om-vault-upgrade` 命令可以将你的内容迁移到最新模板:
```bash
# 1. 克隆最新版 obsidian-mind
git clone https://github.com/breferrari/obsidian-mind.git ~/new-vault
-# 2. 在 Claude Code 中打开
-cd ~/new-vault && claude
+# 2. 用你的 Agent 打开
+cd ~/new-vault && claude # 或 codex、gemini
# 3. 运行升级命令,指向你的旧仓库
/om-vault-upgrade ~/my-old-vault
```
Agent 将会:
-1. **检测** 你的仓库版本(v1–v3.2,或识别为非 obsidian-mind 仓库)
+1. **检测** 你的仓库版本(v1–v3.x,或识别为非 obsidian-mind 仓库)
2. **盘点** 每个文件——分类为用户内容、脚手架、基础设施或未分类
3. **展示迁移计划**——你可以确切看到哪些内容将被复制、转换和跳过
4. **经你批准后执行**——转换 frontmatter、修复 wikilinks、重建索引