Skip to content

Self-evolving second brain with 35 AI skills, 10 agents, and people CRM. Closed-loop harness: a V-model verification lifecycle where the worker never grades its own homework. Plus paired anti-slop design skills for marketing and product UI. Works with Claude Code, Cursor, Kiro, Gemini CLI, Codex.

Add upstream update system, version tracking, content/framework separation (v3.2.0)

Huy Tieu43e5f4947798
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index ea64d2d..352d8b8 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "cog-second-brain",
- "version": "1.0.0",
+ "version": "3.2.0",
"description": "A self-evolving second brain system using Claude Code, Obsidian markdown files, and Git version control. Features specialized AI agents for knowledge management, daily intelligence briefings, and strategic insights extraction.",
"author": {
"name": "Huy Tieu",
@@ -63,6 +63,11 @@
"name": "url-dump",
"path": ".claude/skills/url-dump/SKILL.md",
"description": "Quick capture URLs with automatic content extraction, insights, and categorization into knowledge booklets"
+ },
+ {
+ "name": "update-cog",
+ "path": ".claude/skills/update-cog/SKILL.md",
+ "description": "Check for and apply upstream COG framework updates without touching personal content"
}
],
"metadata": {
diff --git a/.claude/skills/onboarding/SKILL.md b/.claude/skills/onboarding/SKILL.md
index f305050..f9ee357 100644
--- a/.claude/skills/onboarding/SKILL.md
+++ b/.claude/skills/onboarding/SKILL.md
@@ -338,12 +338,22 @@ When you use the braindump skill, select the project to automatically file your
3. **Explore your vault**: All your files are organized in the sidebar
4. **Edit your profile**: Open [[MY-PROFILE]] and customize anytime
+## Keeping COG Updated
+
+COG separates your content from framework files. When new versions are released:
+- Run `/update-cog` to check for and apply updates
+- Or use the shell script: `./cog-update.sh --check`
+- Your braindumps, profiles, and notes are **never** touched by updates
+
+Check your current version: `cat COG-VERSION`
+
## Tips for Success
- **Don't overthink it**: Just dump your thoughts, COG will help organize
- **Be consistent**: Daily briefs and braindumps work best as habits
- **Review weekly**: Use the weekly-checkin skill to see patterns emerge
- **Evolve your setup**: Edit your profile files anytime or run onboarding again to add projects
+- **Stay updated**: Run `/update-cog` periodically to get new skills and improvements
## Getting Help
diff --git a/.claude/skills/update-cog/SKILL.md b/.claude/skills/update-cog/SKILL.md
new file mode 100644
index 0000000..7033202
--- /dev/null
+++ b/.claude/skills/update-cog/SKILL.md
@@ -0,0 +1,99 @@
+---
+name: update-cog
+description: Check for and apply upstream COG framework updates (skills, docs, scripts) without touching personal content
+---
+
+# COG Update Skill
+
+## Purpose
+Help the user update their COG framework files (skills, documentation, scripts) from the official upstream repository without risking their personal content (braindumps, profiles, notes).
+
+## When to Invoke
+- User asks to "update COG", "check for updates", or "get latest COG version"
+- User mentions wanting new skills or features from upstream
+- User asks about their COG version
+
+## Process Flow
+
+### 1. Check Current Version
+Read `COG-VERSION` from the vault root. If it doesn't exist, inform the user they may be on an older version that predates version tracking.
+
+### 2. Ensure Upstream Remote
+```bash
+# Add the upstream remote if not already present
+git remote get-url cog-upstream 2>/dev/null || \
+ git remote add cog-upstream https://github.com/huytieu/COG-second-brain.git
+
+# Fetch latest
+git fetch cog-upstream main --quiet
+```
+
+### 3. Compare Versions
+```bash
+# Local version
+cat COG-VERSION
+
+# Upstream version
+git show cog-upstream/main:COG-VERSION
+```
+
+If versions match, tell the user they're up to date.
+
+### 4. Show What Changed
+For each framework file, compare local vs upstream:
+```bash
+git diff HEAD..cog-upstream/main -- <file>
+```
+
+**Framework files** (safe to update — never contain user content):
+- Core docs: `README.md`, `SETUP.md`, `AGENTS.md`, `GEMINI.md`, `CHANGELOG.md`, `CONTRIBUTING.md`
+- Skills: `.claude/skills/*/SKILL.md`
+- Powers: `.kiro/powers/*/POWER.md`
+- Gemini: `.gemini/commands/*.toml`, `.gemini/skills/*.md`
+- Config: `.claude-plugin/plugin.json`, `marketplace-entry.json`, `.gitignore`
+- Scripts: `cog-update.sh`
+- Version: `COG-VERSION`
+
+### 5. Detect Customizations
+Before updating, check if the user has customized any framework files:
+```bash
+# Compare user's file against the version they originally got
+git diff cog-upstream/main -- <file>
+```
+
+If a file has local customizations, warn the user and offer options:
+- **Keep yours**: Skip this file
+- **Use upstream**: Overwrite with the new version
+- **Backup + update**: Save current as `<file>.backup-YYYYMMDD` then update
+
+### 6. Apply Updates
+For files the user approves:
+```bash
+# Surgical file replacement — no merge, no rebase, zero conflict risk
+git checkout cog-upstream/main -- <file>
+```
+
+### 7. Verify & Summarize
+After updating:
+- Show the new version number
+- List all files that were updated
+- List any files the user chose to skip
+- Suggest committing the update:
+ ```
+ git add -A && git commit -m "Update COG framework to v<new-version>"
+ ```
+
+## Alternative: Shell Script
+For users who prefer a non-AI update, mention the update script:
+```bash
+./cog-update.sh # Interactive
+./cog-update.sh --check # Just check for updates
+./cog-update.sh --dry-run # Preview changes
+./cog-update.sh --force # Update everything
+```
+
+## Important Notes
+- **Content folders are NEVER touched**: `00-inbox/`, `01-daily/`, `02-personal/`, `03-professional/`, `04-projects/`, `05-knowledge/`, `06-templates/` contain user data and are always ignored
+- **The .gitignore is designed** so content folders are excluded from upstream tracking (only `.gitkeep` files are tracked)
+- **The update script updates itself** — `cog-update.sh` is in the framework file list
+- **No merge conflicts possible** — this uses `git checkout` for surgical file replacement, not `git merge` or `git rebase`
diff --git a/.gemini/commands/update-cog.toml b/.gemini/commands/update-cog.toml
new file mode 100644
index 0000000..e501be9
--- /dev/null
+++ b/.gemini/commands/update-cog.toml
@@ -0,0 +1,6 @@
+description = "Check for and apply upstream COG framework updates without touching personal content"
+prompt = """
+You are running the COG update workflow. Follow this playbook exactly:
+
+@{.gemini/skills/update-cog.md}
+"""
diff --git a/.gemini/skills/update-cog.md b/.gemini/skills/update-cog.md
new file mode 100644
index 0000000..ab74a97
--- /dev/null
+++ b/.gemini/skills/update-cog.md
@@ -0,0 +1,64 @@
+# COG Update Playbook
+
+## Goal
+Update COG framework files (skills, docs, scripts) from the official upstream repo without touching personal content.
+
+## Pre-Flight
+1. Read `COG-VERSION` for the current local version
+2. If no version file exists, inform the user they may be on a pre-3.2.0 version
+
+## Steps
+
+### 1. Ensure Upstream Remote
+```bash
+git remote get-url cog-upstream 2>/dev/null || \
+ git remote add cog-upstream https://github.com/huytieu/COG-second-brain.git
+git fetch cog-upstream main --quiet
+```
+
+### 2. Compare Versions
+```bash
+cat COG-VERSION # local
+git show cog-upstream/main:COG-VERSION # upstream
+```
+
+If versions match, tell the user everything is up to date. Done.
+
+### 3. Identify Changed Framework Files
+Compare each framework file against upstream:
+- Core docs: `README.md`, `SETUP.md`, `AGENTS.md`, `GEMINI.md`, `CHANGELOG.md`, `CONTRIBUTING.md`
+- Skills: `.claude/skills/*/SKILL.md`, `.kiro/powers/*/POWER.md`
+- Gemini: `.gemini/commands/*.toml`, `.gemini/skills/*.md`
+- Config: `.claude-plugin/plugin.json`, `marketplace-entry.json`, `.gitignore`
+- Scripts: `cog-update.sh`, `COG-VERSION`
+
+### 4. For Each Changed File
+Ask the user:
+- **Update** — replace with upstream version
+- **Skip** — keep current version
+- **Backup + update** — save `.backup-YYYYMMDD` copy, then replace
+
+### 5. Apply Updates
+```bash
+git checkout cog-upstream/main -- <file>
+```
+
+### 6. Summary
+Show:
+- New version number
+- Files updated
+- Files skipped
+- Suggested commit command
+
+## Shell Script Alternative
+```bash
+./cog-update.sh # Interactive
+./cog-update.sh --check # Check for updates
+./cog-update.sh --dry-run # Preview changes
+./cog-update.sh --force # Update all without prompting
+```
+
+## Safety Guarantees
+- Content folders (`00-inbox/`, `01-daily/`, `02-personal/`, `03-professional/`, `04-projects/`, `05-knowledge/`, `06-templates/`) are NEVER modified
+- Uses `git checkout` for surgical file replacement — no merge, no rebase, zero conflict risk
+- The update script itself is a framework file and self-updates
diff --git a/.gitignore b/.gitignore
index d7bb5a7..826053c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,14 +12,60 @@
.DS_Store
Thumbs.db
-# Personal Content (if sharing COG structure only)
-# Uncomment these if you want to keep your personal content private
-# 00-inbox/*
-# 01-daily/*
-# 02-personal/*
-# 03-professional/*
-# 04-projects/*
-# 05-knowledge/*
+# Personal Content — keep structure (.gitkeep) but ignore user files
+# These are active by default so upstream pulls never conflict with your notes
+
+# 00-inbox: ignore contents, keep .gitkeep
+00-inbox/*
+!00-inbox/.gitkeep
+
+# 01-daily: ignore contents, whitelist subdirs, then ignore their contents
+01-daily/*
+!01-daily/.gitkeep
+!01-daily/briefs/
+01-daily/briefs/*
+!01-daily/briefs/.gitkeep
+!01-daily/checkins/
+01-daily/checkins/*
+!01-daily/checkins/.gitkeep
+
+# 02-personal: ignore contents, whitelist subdirs
+02-personal/*
+!02-personal/.gitkeep
+!02-personal/braindumps/
+02-personal/braindumps/*
+!02-personal/braindumps/.gitkeep
+
+# 03-professional: ignore contents, whitelist subdirs
+03-professional/*
+!03-professional/.gitkeep
+!03-professional/braindumps/
+03-professional/braindumps/*
+!03-professional/braindumps/.gitkeep
+
+# 04-projects: ignore contents, keep .gitkeep
+04-projects/*
+!04-projects/.gitkeep
+
+# 05-knowledge: ignore contents, whitelist subdirs
+05-knowledge/*
+!05-knowledge/.gitkeep
+!05-knowledge/consolidated/
+05-knowledge/consolidated/*
+!05-knowledge/consolidated/.gitkeep
+!05-knowledge/patterns/
+05-knowledge/patterns/*
+!05-knowledge/patterns/.gitkeep
+!05-knowledge/timeline/
+05-knowledge/timeline/*
+!05-knowledge/timeline/.gitkeep
+!05-knowledge/booklets/
+05-knowledge/booklets/*
+!05-knowledge/booklets/.gitkeep
+
+# 06-templates: ignore contents, keep .gitkeep
+06-templates/*
+!06-templates/.gitkeep
# IDE
.vscode/
diff --git a/.kiro/powers/cog-onboarding/POWER.md b/.kiro/powers/cog-onboarding/POWER.md
index f464f86..5796ff5 100644
--- a/.kiro/powers/cog-onboarding/POWER.md
+++ b/.kiro/powers/cog-onboarding/POWER.md
@@ -90,6 +90,8 @@ Create these markdown files:
Create `00-inbox/WELCOME-TO-COG.md` with quick start instructions. Suggest a natural next action (braindump or daily brief) without presenting a numbered menu.
+Also mention that COG can be kept up to date: "When new COG versions are released, run `/update-cog` or `./cog-update.sh` to safely update skills and docs without touching your personal content."
+
## Success Criteria
- MY-PROFILE.md created in 00-inbox/
diff --git a/.kiro/powers/cog-update/POWER.md b/.kiro/powers/cog-update/POWER.md
new file mode 100644
index 0000000..fc36b15
--- /dev/null
+++ b/.kiro/powers/cog-update/POWER.md
@@ -0,0 +1,69 @@
+---
+name: "cog-update"
+displayName: "COG Update"
+description: "Check for and apply upstream COG framework updates without touching personal content"
+keywords: ["update COG", "check updates", "new version", "upgrade COG", "latest COG", "update skills"]
+---
+
+# COG Update Power
+
+Check for and apply upstream COG framework updates (skills, docs, scripts) without touching your personal content.
+
+## When This Power Activates
+
+- User mentions "update COG", "check for updates", or "upgrade"
+- User asks about their COG version or wants new features
+- User wants the latest skills or documentation
+
+## Update Steps
+
+### 1. Check Current Version
+Read `COG-VERSION` in the vault root to determine the local version.
+
+### 2. Fetch Upstream
+```bash
+git remote get-url cog-upstream 2>/dev/null || \
+ git remote add cog-upstream https://github.com/huytieu/COG-second-brain.git
+git fetch cog-upstream main --quiet
+```
+
+### 3. Compare Versions
+```bash
+cat COG-VERSION # local
+git show cog-upstream/main:COG-VERSION # upstream
+```
+
+If versions match, report that everything is up to date.
+
+### 4. Review Changed Files
+Compare each framework file (skills, docs, scripts) against upstream. Framework files are safe to update — they never contain user content.
+
+For each changed file, offer the user:
+- **Update**: Replace with upstream version
+- **Skip**: Keep the current local version
+- **Backup + update**: Save a `.backup-YYYYMMDD` copy, then update
+
+### 5. Apply Updates
+```bash
+git checkout cog-upstream/main -- <file>
+```
+
+### 6. Summarize
+Report the new version, list updated files, and suggest committing:
+```
+git add -A && git commit -m "Update COG framework to v<version>"
+```
+
+## Shell Script Alternative
+Users can also update without an AI agent:
+```bash
+./cog-update.sh # Interactive
+./cog-update.sh --check # Check only
+./cog-update.sh --dry-run # Preview
+./cog-update.sh --force # Update all
+```
+
+## Safety
+- Content folders (`00-inbox/`, `01-daily/`, `02-personal/`, etc.) are NEVER touched
+- Uses surgical `git checkout` — no merge conflicts possible
+- Backs up customized files before overwriting
diff --git a/00-inbox/.gitkeep b/00-inbox/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/01-daily/.gitkeep b/01-daily/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/01-daily/briefs/.gitkeep b/01-daily/briefs/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/01-daily/checkins/.gitkeep b/01-daily/checkins/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/02-personal/.gitkeep b/02-personal/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/02-personal/braindumps/.gitkeep b/02-personal/braindumps/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/03-professional/.gitkeep b/03-professional/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/03-professional/braindumps/.gitkeep b/03-professional/braindumps/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/04-projects/.gitkeep b/04-projects/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/05-knowledge/.gitkeep b/05-knowledge/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/05-knowledge/booklets/.gitkeep b/05-knowledge/booklets/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/05-knowledge/consolidated/.gitkeep b/05-knowledge/consolidated/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/05-knowledge/patterns/.gitkeep b/05-knowledge/patterns/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/05-knowledge/timeline/.gitkeep b/05-knowledge/timeline/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/06-templates/.gitkeep b/06-templates/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/AGENTS.md b/AGENTS.md
index 74b9728..ddebb77 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -207,6 +207,40 @@ This document defines the available commands/skills for AI agents interacting wi
---
+### /update-cog
+
+**Description:** Check for and apply upstream COG framework updates without touching personal content.
+
+**Triggers:**
+- `/update-cog`
+- "update COG"
+- "check for updates"
+- "get latest COG version"
+- "upgrade COG"
+- "new COG version"
+
+**Purpose:** Safely update framework files (skills, docs, scripts) from the official upstream repository while leaving all personal content untouched.
+
+**What it does:**
+1. Reads `COG-VERSION` to determine current version
+2. Adds/fetches the `cog-upstream` remote from the official repo
+3. Compares each framework file against upstream
+4. Detects customizations and offers per-file keep/overwrite/backup
+5. Applies updates via surgical `git checkout` (no merge conflicts)
+6. Reports updated files and suggests committing
+
+**Shell script alternative:**
+```bash
+./cog-update.sh # Interactive
+./cog-update.sh --check # Check for updates
+./cog-update.sh --dry-run # Preview changes
+./cog-update.sh --force # Update all without prompting
+```
+
+**Safety:** Content folders (`00-inbox/`, `01-daily/`, `02-personal/`, etc.) are NEVER touched. Only framework files (skills, docs, scripts) are updated.
+
+---
+
## Vault Structure
```
@@ -258,6 +292,14 @@ All configuration is stored as readable markdown files:
Edit these files anytime - changes take effect immediately.
+## Version & Updates
+
+COG tracks its version in `COG-VERSION` (currently 3.2.0). To check for updates:
+- Run `/update-cog` in any supported agent
+- Or use the shell script: `./cog-update.sh --check`
+
+Updates only touch framework files (skills, docs, scripts) — your personal content is never modified.
+
---
## Task Format
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8cb614a..356219e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,61 @@
All notable changes to COG (Cognition + Obsidian + Git) will be documented in this file.
+## [3.2.0] - 2026-02-09
+
+### Upstream Update System
+
+Users who fork or clone COG can now safely pull framework updates (skills, docs, scripts) without risking merge conflicts with their personal content.
+
+### Added
+
+#### Update Tooling
+- **`cog-update.sh`** — Interactive bash script for updating framework files
+ - `--check`: See available updates without making changes
+ - `--dry-run`: Preview what would change
+ - `--force`: Update all framework files at once
+ - Interactive mode: Per-file prompts with diff, backup, and skip options
+- **`/update-cog` skill** — Available in all 4 agent formats:
+ - `.claude/skills/update-cog/SKILL.md` (Claude Code)
+ - `.kiro/powers/cog-update/POWER.md` (Kiro)
+ - `.gemini/commands/update-cog.toml` + `.gemini/skills/update-cog.md` (Gemini CLI)
+ - `AGENTS.md` updated with `/update-cog` command (OpenAI Codex, others)
+- **`COG-VERSION`** — Single-line version tracking file (currently `3.2.0`)
+
+#### Content/Framework Separation
+- **`.gitkeep` files** in all 15 content directories — preserves directory structure in upstream while `.gitignore` excludes user content
+- **`.gitignore` rewrite** — Content folder ignores now active by default with `.gitkeep` whitelisting
+
+#### Directory Structure Preservation
+- `.gitkeep` added to: `00-inbox/`, `01-daily/`, `01-daily/briefs/`, `01-daily/checkins/`, `02-personal/`, `02-personal/braindumps/`, `03-professional/`, `03-professional/braindumps/`, `04-projects/`, `05-knowledge/`, `05-knowledge/consolidated/`, `05-knowledge/patterns/`, `05-knowledge/timeline/`, `05-knowledge/booklets/`, `06-templates/`
+
+### Changed
+
+#### Documentation
+- **`README.md`** — Added "Keeping COG Updated" section, FAQ entries for updates, updated roadmap
+- **`SETUP.md`** — Added comprehensive "Keeping COG Updated" section with all 3 update methods
+- **`AGENTS.md`** — Added `/update-cog` command, version & updates configuration section
+- **`GEMINI.md`** — Added `/update-cog` to available skills list
+- **`CONTRIBUTING.md`** — Added version bump protocol to "Before You Start" section
+- **`CHANGELOG.md`** — This entry
+
+#### Integration
+- **`.claude-plugin/plugin.json`** — Added update-cog skill, bumped version to 3.2.0
+- **`marketplace-entry.json`** — Bumped version to 3.2.0
+- **`.claude/skills/onboarding/SKILL.md`** — Added "Keeping COG Updated" to welcome guide template
+- **`.kiro/powers/cog-onboarding/POWER.md`** — Added update mention to wrap-up section
+
+### Removed
+- **`example-vault/`** — Removed empty directory (contained only `.DS_Store`), replaced by `.gitkeep` files
+
+### Design Decisions
+- **Remote name `cog-upstream`**: Works for both fork and clone users without conflicting with `origin`
+- **`git checkout <remote>/<branch> -- <file>`**: Surgical file replacement with zero conflict risk
+- **Self-updating script**: `cog-update.sh` is in the framework file list, so it updates itself
+- **Active .gitignore**: Content folder ignores are on by default so new users get safe defaults
+
+---
+
## [3.1.0] - 2026-02-03
### Obsidian Tasks Plugin Integration
diff --git a/COG-VERSION b/COG-VERSION
new file mode 100644
index 0000000..944880f
--- /dev/null
+++ b/COG-VERSION
@@ -0,0 +1 @@
+3.2.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 80a5ede..6b626cf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -36,6 +36,11 @@ We welcome ideas for new features or improvements:
- Plain text over proprietary formats
- Self-evolving intelligence
- Verification-first approach
+4. **If your PR changes the framework** (skills, docs, scripts):
+ - Bump the version in `COG-VERSION` (e.g., `3.2.0` → `3.3.0`)
+ - Add a changelog entry in `CHANGELOG.md`
+ - If adding a new file, add it to the `FRAMEWORK_FILES` array in `cog-update.sh`
+ - Update `marketplace-entry.json` and `.claude-plugin/plugin.json` version fields
#### Making Changes
diff --git a/GEMINI.md b/GEMINI.md
index 5c78657..ee3c417 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -26,7 +26,7 @@ Read `03-professional/COMPETITIVE-WATCHLIST.md` for companies to track.
## Available Skills
-Use `/onboarding`, `/braindump`, `/daily-brief`, `/weekly-checkin`, `/knowledge-consolidation`, or `/url-dump` to invoke COG skills. Each has a detailed playbook in `.gemini/skills/`.
+Use `/onboarding`, `/braindump`, `/daily-brief`, `/weekly-checkin`, `/knowledge-consolidation`, `/url-dump`, or `/update-cog` to invoke COG skills. Each has a detailed playbook in `.gemini/skills/`.
## Rules
diff --git a/README.md b/README.md
index 3ce9dad..5f1402d 100644
--- a/README.md
+++ b/README.md
@@ -395,9 +395,40 @@ Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
- Documentation enhancements
- Example workflows
+## Keeping COG Updated
+
+COG separates **framework files** (skills, docs, scripts) from **your content** (braindumps, profiles, notes). When new versions are released, you can safely update framework files without risking your personal data.
+
+### Three Ways to Update
+
+**1. AI Agent (any supported agent):**
+```
+"Update COG" or /update-cog
+```
+
+**2. Shell Script:**
+```bash
+./cog-update.sh # Interactive — prompts per file
+./cog-update.sh --check # Just check for updates
+./cog-update.sh --dry-run # Preview what would change
+./cog-update.sh --force # Update everything
+```
+
+**3. Manual Git:**
+```bash
+git remote add cog-upstream https://github.com/huytieu/COG-second-brain.git
+git fetch cog-upstream main
+git checkout cog-upstream/main -- README.md SETUP.md .claude/skills/ .kiro/powers/ # etc
+```
+
+Your content folders (`00-inbox/`, `01-daily/`, `02-personal/`, etc.) are **never touched** by updates. Only framework files (skills, docs, scripts) are replaced.
+
+Check your current version: `cat COG-VERSION`
+
## Roadmap
-- [ ] Gemini support (in addition to Claude)
+- [x] ~~Gemini support~~ (shipped in v3.0)
+- [ ] Upstream update system (safe framework updates without merge conflicts)
- [ ] Web interface for knowledge graph visualization
- [ ] Mobile-first commands (optimized for Obsidian mobile)
- [ ] Team collaboration features (with privacy preservation)
@@ -437,6 +468,12 @@ A: Currently designed for personal use. Team features planned for future release
**Q: What if I don't use Git?**
A: Git is optional but recommended for version history. COG works fine without it using just iCloud sync.
+**Q: How do I get new skills and features?**
+A: Run `/update-cog` in any supported agent, or use `./cog-update.sh` from the terminal. Updates only touch framework files — your notes are never modified. See [Keeping COG Updated](#keeping-cog-updated).
+
+**Q: Will updating overwrite my customizations?**
+A: The update process detects customized files and lets you choose per-file: keep yours, use upstream, or backup + update. Nothing is overwritten without your approval (unless you use `--force`).
+
## License
MIT License - see [LICENSE](LICENSE) for details.
diff --git a/SETUP.md b/SETUP.md
index 5a4dd11..993a0a6 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -403,6 +403,76 @@ First of the month:
Analyze accumulated braindumps, build frameworks
```
+## Keeping COG Updated
+
+When new COG versions are released (new skills, improved docs, bug fixes), you can safely update framework files without touching your personal content.
+
+### Method 1: AI Agent (Recommended)
+
+Ask any supported agent:
+```
+"Update COG" or /update-cog
+```
+
+The agent will:
+1. Check your current version against upstream
+2. Show what's changed
+3. Let you approve updates per-file (with backup option for customized files)
+4. Apply updates and suggest a commit
+
+### Method 2: Shell Script
+
+```bash
+# Check for available updates (no changes made)
+./cog-update.sh --check
+
+# Preview what would change (no changes made)
+./cog-update.sh --dry-run
+
+# Interactive update — prompts for each file
+./cog-update.sh
+
+# Update everything without prompting
+./cog-update.sh --force
+```
+
+### Method 3: Manual Git
+
+```bash
+# One-time setup: add the upstream remote
+git remote add cog-upstream https://github.com/huytieu/COG-second-brain.git
+
+# Fetch latest
+git fetch cog-upstream main
+
+# Update specific files (surgical replacement, no merge needed)
+git checkout cog-upstream/main -- README.md SETUP.md AGENTS.md
+git checkout cog-upstream/main -- .claude/skills/ .kiro/powers/ .gemini/
+git checkout cog-upstream/main -- COG-VERSION cog-update.sh
+
+# Commit the update
+git add -A && git commit -m "Update COG framework to v$(cat COG-VERSION)"
+```
+
+### What Gets Updated vs What Doesn't
+
+| Updated (framework files) | Never touched (your content) |
+|---|---|
+| Skills (`.claude/skills/`, `.kiro/powers/`, `.gemini/`) | `00-inbox/` (profiles, notes) |
+| Docs (`README.md`, `SETUP.md`, `AGENTS.md`, etc.) | `01-daily/` (briefs, checkins) |
+| Scripts (`cog-update.sh`) | `02-personal/` (braindumps) |
+| Config (`.gitignore`, `plugin.json`) | `03-professional/` (braindumps) |
+| Version (`COG-VERSION`) | `04-projects/` (project files) |
+| | `05-knowledge/` (consolidated) |
+| | `06-templates/` (your templates) |
+
+### Checking Your Version
+
+```bash
+cat COG-VERSION
+# or ask any agent: "What version of COG am I running?"
+```
+
## Getting Help
- **Issues:** https://github.com/huytieu/COG-second-brain/issues
diff --git a/cog-update.sh b/cog-update.sh
new file mode 100755
index 0000000..e818268
--- /dev/null
+++ b/cog-update.sh
@@ -0,0 +1,360 @@
+#!/usr/bin/env bash
+# COG Upstream Update Script
+# Safely updates framework files (skills, docs, scripts) without touching your personal content.
+#
+# Usage:
+# ./cog-update.sh Interactive update
+# ./cog-update.sh --check Check for available updates (no changes)
+# ./cog-update.sh --dry-run Show what would change (no changes)
+# ./cog-update.sh --force Update all framework files without prompting
+# ./cog-update.sh --help Show this help message
+
+set -euo pipefail
+
+# ── Configuration ────────────────────────────────────────────────────
+REMOTE_NAME="cog-upstream"
+REMOTE_URL="https://github.com/huytieu/COG-second-brain.git"
+BRANCH="main"
+VERSION_FILE="COG-VERSION"
+
+# Framework files — these are safe to overwrite (your content is never in this list)
+FRAMEWORK_FILES=(
+ # Core docs
+ "README.md"
+ "SETUP.md"
+ "AGENTS.md"
+ "GEMINI.md"
+ "CHANGELOG.md"
+ "CONTRIBUTING.md"
+ "LICENSE"
+ "COG-VERSION"
+ "cog-update.sh"
+
+ # Claude Code skills
+ ".claude/skills/onboarding/SKILL.md"
+ ".claude/skills/braindump/SKILL.md"
+ ".claude/skills/daily-brief/SKILL.md"
+ ".claude/skills/weekly-checkin/SKILL.md"
+ ".claude/skills/knowledge-consolidation/SKILL.md"
+ ".claude/skills/url-dump/SKILL.md"
+ ".claude/skills/update-cog/SKILL.md"
+
+ # Kiro powers
+ ".kiro/powers/cog-onboarding/POWER.md"
+ ".kiro/powers/cog-braindump/POWER.md"
+ ".kiro/powers/cog-daily-brief/POWER.md"
+ ".kiro/powers/cog-weekly-checkin/POWER.md"
+ ".kiro/powers/cog-knowledge-consolidation/POWER.md"
+ ".kiro/powers/cog-url-dump/POWER.md"
+ ".kiro/powers/cog-update/POWER.md"
+
+ # Gemini CLI
+ ".gemini/commands/onboarding.toml"
+ ".gemini/commands/braindump.toml"
+ ".gemini/commands/daily-brief.toml"
+ ".gemini/commands/weekly-checkin.toml"
+ ".gemini/commands/knowledge-consolidation.toml"
+ ".gemini/commands/url-dump.toml"
+ ".gemini/commands/update-cog.toml"
+ ".gemini/skills/onboarding.md"
+ ".gemini/skills/braindump.md"
+ ".gemini/skills/daily-brief.md"
+ ".gemini/skills/weekly-checkin.md"
+ ".gemini/skills/knowledge-consolidation.md"
+ ".gemini/skills/url-dump.md"
+ ".gemini/skills/update-cog.md"
+
+ # Plugin metadata
+ ".claude-plugin/plugin.json"
+ "marketplace-entry.json"
+
+ # Git infrastructure
+ ".gitignore"
+)
+
+# ── Helpers ──────────────────────────────────────────────────────────
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+info() { echo -e "${CYAN}ℹ${RESET} $*"; }
+ok() { echo -e "${GREEN}✓${RESET} $*"; }
+warn() { echo -e "${YELLOW}⚠${RESET} $*"; }
+err() { echo -e "${RED}✗${RESET} $*" >&2; }
+
+usage() {
+ cat <<'EOF'
+COG Upstream Update Script
+
+Updates framework files (skills, docs, scripts) from the official COG repo
+without touching your personal content (braindumps, profiles, notes).
+
+Usage:
+ ./cog-update.sh Interactive update (prompts per file)
+ ./cog-update.sh --check Check for available updates (no changes)
+ ./cog-update.sh --dry-run Show what would change (no changes)
+ ./cog-update.sh --force Update all framework files without prompting
+ ./cog-update.sh --help Show this help message
+
+How it works:
+ 1. Adds/fetches the upstream remote (cog-upstream)
+ 2. Compares each framework file against the upstream version
+ 3. Offers to update changed files (interactive mode) or updates all (--force)
+ 4. Your content folders (00-inbox, 01-daily, etc.) are NEVER modified
+
+Safe to run anytime — your notes, profiles, and braindumps are never touched.
+EOF
+}
+
+# ── Ensure remote exists & fetch ─────────────────────────────────────
+ensure_remote() {
+ if ! git remote get-url "$REMOTE_NAME" &>/dev/null; then
+ info "Adding remote ${BOLD}${REMOTE_NAME}${RESET} → ${REMOTE_URL}"
+ git remote add "$REMOTE_NAME" "$REMOTE_URL"
+ fi
+ info "Fetching latest from ${BOLD}${REMOTE_NAME}/${BRANCH}${RESET}..."
+ git fetch "$REMOTE_NAME" "$BRANCH" --quiet
+}
+
+# ── Get local and upstream versions ──────────────────────────────────
+local_version() {
+ if [[ -f "$VERSION_FILE" ]]; then
+ cat "$VERSION_FILE" | tr -d '[:space:]'
+ else
+ echo "unknown"
+ fi
+}
+
+upstream_version() {
+ git show "${REMOTE_NAME}/${BRANCH}:${VERSION_FILE}" 2>/dev/null | tr -d '[:space:]' || echo "unknown"
+}
+
+# ── Diff a single file ──────────────────────────────────────────────
+file_has_changes() {
+ local file="$1"
+ # File exists upstream?
+ if ! git show "${REMOTE_NAME}/${BRANCH}:${file}" &>/dev/null; then
+ return 1 # no upstream version
+ fi
+ # File differs from upstream?
+ if [[ -f "$file" ]]; then
+ ! diff -q <(git show "${REMOTE_NAME}/${BRANCH}:${file}" 2>/dev/null) "$file" &>/dev/null
+ else
+ return 0 # file missing locally → counts as changed
+ fi
+}
+
+# ── Update a single file from upstream ───────────────────────────────
+update_file() {
+ local file="$1"
+ local dir
+ dir=$(dirname "$file")
+ [[ "$dir" != "." ]] && mkdir -p "$dir"
+ git show "${REMOTE_NAME}/${BRANCH}:${file}" > "$file" 2>/dev/null
+}
+
+# ── Backup a file before overwriting ─────────────────────────────────
+backup_file() {
+ local file="$1"
+ if [[ -f "$file" ]]; then
+ local backup="${file}.backup-$(date +%Y%m%d-%H%M%S)"
+ cp "$file" "$backup"
+ echo "$backup"
+ fi
+}
+
+# ── Main logic ───────────────────────────────────────────────────────
+main() {
+ local mode="interactive"
+
+ while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --check) mode="check"; shift ;;
+ --dry-run) mode="dry-run"; shift ;;
+ --force) mode="force"; shift ;;
+ --help|-h) usage; exit 0 ;;
+ *) err "Unknown option: $1"; usage; exit 1 ;;
+ esac
+ done
+
+ # Sanity check — are we in a git repo?
+ if ! git rev-parse --is-inside-work-tree &>/dev/null; then
+ err "Not inside a git repository. Run this from your COG folder."
+ exit 1
+ fi
+
+ echo ""
+ echo -e "${BOLD}COG Upstream Update${RESET}"
+ echo -e "─────────────────────"
+ echo ""
+
+ ensure_remote
+
+ local lv uv
+ lv=$(local_version)
+ uv=$(upstream_version)
+
+ info "Local version: ${BOLD}${lv}${RESET}"
+ info "Upstream version: ${BOLD}${uv}${RESET}"
+ echo ""
+
+ if [[ "$uv" == "unknown" ]]; then
+ err "Could not read upstream version. Check your internet connection."
+ exit 1
+ fi
+
+ # Collect changed files
+ local changed=()
+ local new_files=()
+ for file in "${FRAMEWORK_FILES[@]}"; do
+ if file_has_changes "$file"; then
+ if [[ -f "$file" ]]; then
+ changed+=("$file")
+ else
+ new_files+=("$file")
+ fi
+ fi
+ done
+
+ local total=$(( ${#changed[@]} + ${#new_files[@]} ))
+
+ if [[ $total -eq 0 ]]; then
+ ok "Everything is up to date! (v${lv})"
+ exit 0
+ fi
+
+ info "${BOLD}${#changed[@]}${RESET} file(s) changed, ${BOLD}${#new_files[@]}${RESET} new file(s) available"
+ echo ""
+
+ # ── Check mode ───────────────────────────────────────────────────
+ if [[ "$mode" == "check" ]]; then
+ if [[ ${#changed[@]} -gt 0 ]]; then
+ echo -e "${BOLD}Changed:${RESET}"
+ for f in "${changed[@]}"; do echo " ~ $f"; done
+ fi
+ if [[ ${#new_files[@]} -gt 0 ]]; then
+ echo -e "${BOLD}New:${RESET}"
+ for f in "${new_files[@]}"; do echo " + $f"; done
+ fi
+ echo ""
+ info "Run ${BOLD}./cog-update.sh${RESET} to update, or ${BOLD}./cog-update.sh --dry-run${RESET} to preview."
+ exit 0
+ fi
+
+ # ── Dry-run mode ─────────────────────────────────────────────────
+ if [[ "$mode" == "dry-run" ]]; then
+ echo -e "${BOLD}Dry run — no changes will be made:${RESET}"
+ echo ""
+ if [[ ${#changed[@]} -gt 0 ]]; then
+ echo "Would update:"
+ for f in "${changed[@]}"; do echo " ~ $f"; done
+ fi
+ if [[ ${#new_files[@]} -gt 0 ]]; then
+ echo "Would create:"
+ for f in "${new_files[@]}"; do echo " + $f"; done
+ fi
+ echo ""
+ info "Run ${BOLD}./cog-update.sh --force${RESET} to apply all, or ${BOLD}./cog-update.sh${RESET} for interactive mode."
+ exit 0
+ fi
+
+ # ── Force mode ───────────────────────────────────────────────────
+ if [[ "$mode" == "force" ]]; then
+ local updated=0
+ for f in "${changed[@]}" "${new_files[@]}"; do
+ if [[ -f "$f" ]]; then
+ backup_file "$f" >/dev/null
+ fi
+ update_file "$f"
+ ok "Updated: $f"
+ ((updated++))
+ done
+ echo ""
+ ok "Updated ${updated} file(s) to v${uv}"
+ info "Backups saved as *.backup-YYYYMMDD-HHMMSS alongside originals"
+ exit 0
+ fi
+
+ # ── Interactive mode ─────────────────────────────────────────────
+ local updated=0 skipped=0
+
+ # New files first
+ if [[ ${#new_files[@]} -gt 0 ]]; then
+ echo -e "${BOLD}New files available:${RESET}"
+ for f in "${new_files[@]}"; do
+ echo -ne " ${GREEN}+${RESET} ${f} — add? [Y/n] "
+ read -r answer
+ if [[ -z "$answer" || "$answer" =~ ^[Yy] ]]; then
+ update_file "$f"
+ ok "Added: $f"
+ ((updated++))
+ else
+ warn "Skipped: $f"
+ ((skipped++))
+ fi
+ done
+ echo ""
+ fi
+
+ # Changed files
+ if [[ ${#changed[@]} -gt 0 ]]; then
+ echo -e "${BOLD}Changed files:${RESET}"
+ for f in "${changed[@]}"; do
+ echo -ne " ${YELLOW}~${RESET} ${f} — update? [Y/n/d(iff)/b(ackup+update)] "
+ read -r answer
+ case "$answer" in
+ d|D|diff)
+ diff --color=auto <(cat "$f") <(git show "${REMOTE_NAME}/${BRANCH}:${f}") || true
+ echo -ne " Update this file? [Y/n/b] "
+ read -r answer2
+ if [[ -z "$answer2" || "$answer2" =~ ^[Yy] ]]; then
+ update_file "$f"
+ ok "Updated: $f"
+ ((updated++))
+ elif [[ "$answer2" =~ ^[Bb] ]]; then
+ local bk
+ bk=$(backup_file "$f")
+ update_file "$f"
+ ok "Updated: $f (backup: $bk)"
+ ((updated++))
+ else
+ warn "Skipped: $f"
+ ((skipped++))
+ fi
+ ;;
+ b|B)
+ local bk
+ bk=$(backup_file "$f")
+ update_file "$f"
+ ok "Updated: $f (backup: $bk)"
+ ((updated++))
+ ;;
+ n|N)
+ warn "Skipped: $f"
+ ((skipped++))
+ ;;
+ *)
+ update_file "$f"
+ ok "Updated: $f"
+ ((updated++))
+ ;;
+ esac
+ done
+ fi
+
+ echo ""
+ echo -e "${BOLD}Summary:${RESET}"
+ ok "${updated} file(s) updated"
+ [[ $skipped -gt 0 ]] && warn "${skipped} file(s) skipped"
+ echo ""
+
+ if [[ $updated -gt 0 ]]; then
+ info "Review changes with ${BOLD}git diff${RESET}, then commit when ready:"
+ echo " git add -A && git commit -m \"Update COG framework to v${uv}\""
+ fi
+}
+
+main "$@"
diff --git a/marketplace-entry.json b/marketplace-entry.json
index 8405950..0ddc5fc 100644
--- a/marketplace-entry.json
+++ b/marketplace-entry.json
@@ -7,5 +7,5 @@
"url": "https://github.com/huytieu"
},
"description": "Self-evolving second brain with AI agents for knowledge management",
- "version": "1.0.0"
+ "version": "3.2.0"
}