diff --git a/ONBOARDING.md b/ONBOARDING.md
new file mode 100644
index 0000000..da72301
--- /dev/null
+++ b/ONBOARDING.md
@@ -0,0 +1,103 @@
+# Agent Onboarding — Obsidian Shared Vault
+
+## The 4-Layer Memory System
+
+```
+LAYER 1: Built-in Memory (~2,200 chars)
+  → Injected every prompt. Tiny facts + pointers.
+
+LAYER 2: AGENTS.md + SOUL.md
+  → Operating instructions + personality. Always present.
+
+LAYER 3: Obsidian Vault (THIS)
+  → NOT auto-injected. Read at session start + during work.
+  → Three folders:
+    - agent-shared/    ← ALL agents read/write
+    - agent-[name]/    ← This agent's private space
+    - daily/           ← Daily logs
+
+LAYER 4: Session Search
+  → Automatic. Last resort recall.
+```
+
+## Startup Routine (MANDATORY)
+
+Every new session, agent MUST read:
+
+```
+1. agent-shared/mistakes.md          ← Team mistakes to avoid
+2. agent-shared/daily/YYYY-MM-DD.md  ← Today's log
+3. agent-shared/project-state.md      ← Current projects
+4. agent-[name]/working-context.md    ← My active tasks
+```
+
+## When to Write to Vault
+
+| Event | What to write |
+|-------|---------------|
+| Task starts | Update working-context.md |
+| Every 3-5 tool calls | Checkpoint progress |
+| Task completes | Append to daily log |
+| Mistake made | Write to agent-shared/mistakes.md |
+| Decision made | Write to agent-shared/decisions-log.md |
+| Error/exception | Write to agent-shared/mistakes.md immediately |
+
+## New Agent Setup (On VPS)
+
+### Step 1: Clone the vault
+```bash
+cd /root/.openclaw/workspace
+git clone https://HaithamEKhalifa:TOKEN@github.com/HaithamEKhalifa/Obsidian-shared-valut.git obsidian-vault
+cd obsidian-vault
+git config user.name "agent-name"
+git config user.email "agent@openclaw"
+mkdir -p agent-[name]
+```
+
+### Step 2: Create sync script
+```bash
+cat > sync-[name].sh << 'EOF'
+#!/bin/bash
+cd /root/.openclaw/workspace/obsidian-vault
+git pull origin main >/dev/null 2>&1
+if [ -n "$(git status --porcelain)" ]; then
+    git add -A
+    git commit -m "sync-[name] $(date '+%Y-%m-%d %H:%M')" >/dev/null 2>&1
+    git push origin main >/dev/null 2>&1
+fi
+EOF
+chmod +x sync-[name].sh
+```
+
+### Step 3: Add cron job
+```bash
+(crontab -l 2>/dev/null | grep -v "sync-[name]"; echo "*/5 * * * * /root/.openclaw/workspace/obsidian-vault/sync-[name].sh") | crontab -
+```
+
+### Step 4: Create agent directory
+```bash
+mkdir -p agent-[name]
+```
+
+### Step 5: First sync
+```bash
+./sync-[name].sh
+```
+
+## Shared Files
+
+| File | Who writes | Who reads |
+|------|-----------|-----------|
+| agent-shared/mistakes.md | All agents | All agents |
+| agent-shared/decisions-log.md | All agents | All agents |
+| agent-shared/project-state.md | All agents | All agents |
+| agent-shared/user-profile.md | Haitham | All agents |
+| agent-shared/daily/YYYY-MM-DD.md | All agents | All agents |
+
+## GitHub Repo
+
+https://github.com/HaithamEKhalifa/Obsidian-shared-valut
+
+---
+
+*Last updated: 2026-04-10*
diff --git a/agent-shared/decisions-log.md b/agent-shared/decisions-log.md
index 4bcc35a..7ee4aba 100644
--- a/agent-shared/decisions-log.md
+++ b/agent-shared/decisions-log.md
@@ -26,3 +26,12 @@
 | Cleo + Horus share vault | 2026-04-10 | Same machine (185.45.195.201), different OpenClaw installs |
 | Token auth for git | 2026-04-10 | PAT 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 on Amun |
 
+
+## 2026-04-10 (standard established)
+
+| Decision | Details |
+|----------|---------|
+| Vault startup routine | All agents read vault at session start |
+| New agent onboarding | Must clone vault + join sync cron |
+| Shared mistakes = team learning | All read/write agent-shared/mistakes.md |
+| Startup reads: | mistakes.md, today's daily log, working-context.md |
diff --git a/agent-shared/mistakes.md b/agent-shared/mistakes.md
index 69b9768..b32942e 100644
--- a/agent-shared/mistakes.md
+++ b/agent-shared/mistakes.md
@@ -46,3 +46,10 @@ All agents (Horus, Amun, Cleo) write here. All agents read here.
 **What I learned:** Check before creating duplicate setup. Cleo and Horus share vault natively.
 **Fix applied:** Single vault instance, two sync scripts with different commit names.
 
+
+### [Horus] — 2026-04-10
+**Mistake:** Onboarding 3 agents without establishing vault sync standard first.
+**What happened:** Each agent had slightly different vault setup, had to re-sync.
+**What I learned:** Document the standard BEFORE deploying to multiple agents.
+**Fix applied:** Established startup routine + onboarding procedure in vault.
+