obsidian/CLAUDE.md

# Claude Code – Vault Orientation

## Who I Am
I'm Claude Code, acting as Vadym's AI partner for all Oliver Agency projects.
This vault is my persistent memory. I read it at the start of every session and update it after every meaningful change.

## Model for Logging
**Always use `claude-haiku-4-5-20251001` (Haiku)** for all Obsidian logging and note-writing operations. This keeps costs low and responses fast for pure logging tasks.

## Vault Structure
```
VadymSamoilenko/
├── raw/                 ← YOUR inbox — dump source material here (articles, PDFs, clips)
│   └── _processed/      ← Compiled files move here (don't delete)
├── wiki/                ← LLM's domain — Karpathy-style knowledge base (see Wiki System below)
│   ├── _master-index.md ← LLM's table of contents — read this first for any query
│   ├── log.md           ← Append-only build log
│   ├── concepts/        ← Atomic knowledge articles (+ _index.md)
│   ├── connections/     ← Cross-cutting insights (+ _index.md)
│   └── qa/              ← Filed query answers (+ _index.md)
├── output/              ← Query results, reports, slide decks
│   └── slide-decks/
├── 01 Projects/         ← One folder per project (matches disk: /Volumes/SSD/Projects/Oliver/)
│   ├── {project}/       ← Each project has one .md note
│   ├── Dashboard.md     ← Live Dataview dashboard
│   ├── Projects.base    ← Obsidian Bases view
│   └── Projects Index.md
├── 02 Areas/
│   ├── Pending Commands.md  ← ⚠️ IMPORTANT: track all server commands given to Vadym
│   └── Work Tasks.md
├── 03 Resources/
│   ├── Infrastructure/  ← SSH Servers, Deploy guides, cheatsheets
│   └── SOPs/
├── 04 Archive/          ← Completed/abandoned projects
├── 05 Aimpress LTD/     ← Personal company (credentials at ~/.secrets/)
├── 99 Daily/            ← Daily session logs (YYYY-MM-DD.md)
└── Templates/
```

## obsidian-skills
Five official skills from Kepano are installed in `.agents/skills/` and symlinked to `.claude/skills/`:
- **obsidian-cli** — CLI commands for reading/writing notes (requires Obsidian open with CLI enabled)
- **obsidian-markdown** — Obsidian Flavored Markdown syntax reference
- **obsidian-bases** — Creating and editing `.base` files
- **json-canvas** — Creating canvas files
- **defuddle** — Extract clean markdown from web pages

## Project Notes – What to Track
Each project note lives at `01 Projects/{project-dir}/{Project Name}.md` and must contain:
- **frontmatter**: name, client, status, tech, local_path, deploy, url, tags
- **Overview**: what the project does
- **Tech Stack**: frontend / backend / db / infra
- **Deployment**: how to run it, where it lives
- **Sessions**: reverse-chronological log (latest first)
- **Change Log**: table of date / requested / changed / files
- **Related**: wikilinks to connected notes

## Frontmatter Standard
```yaml
name: "Human-readable name"
client: "Client Name"           # or "Oliver Internal"
status: active                  # active | production | paused | archived
tech: [Python, FastAPI, Docker] # array
local_path: /Users/ai_leed/Documents/Projects/Oliver/{dirname}
deploy: "docker compose up --build"
url: https://...                # if deployed
server: GCP | optical-web-1 | TBD
tags:
  - project
  - client/ford                 # see Tag Taxonomy below
created: YYYY-MM-DD
```

## Tag Taxonomy
Use these tags consistently across all notes:

```
# Client tags
client/3m, client/barclays, client/ferrero, client/ford,
client/hm, client/loreal, client/lusa, client/pimco,
client/solventum, client/dowjones

# Status tags
status/active, status/production, status/paused, status/archived

# Tech tags
tech/fastapi, tech/react, tech/docker, tech/nextjs,
tech/gemini, tech/claude, tech/python, tech/node

# Type tags
type/project, type/dashboard, type/sop, type/reference,
type/daily, type/review, type/meeting

# Domain tags
domain/ai, domain/accessibility, domain/devops, domain/analytics
```

## Project Status Lifecycle
- **`active`** — currently being developed or maintained
- **`production`** — deployed and stable, not under active development
- **`paused`** — on hold, may resume
- **`archived`** — completed or abandoned

### Archival workflow
When a project moves to `archived`:
1. Update frontmatter `status: archived`
2. Move folder from `01 Projects/{name}/` → `04 Archive/{name}/`
3. Update Projects Index.md to remove or annotate the entry

## Session Protocol — MANDATORY

### Start of every session:
1. Check `01 Projects/{project}/` — the relevant project note (pre-loaded via SessionStart hook)
2. Check `02 Areas/Pending Commands.md` — any server commands still outstanding?
3. If the project note is a **stub** (never had a real session) → read the project's code first and fill in Overview, Tech Stack, Deployment before starting work

### During every session:
- If I give Vadym a **command to run on a server or locally** → immediately add to `02 Areas/Pending Commands.md` under **Pending**
- Once Vadym confirms it ran → move to **Done** with result
- If any service is **installed, removed, or renamed** on any homelab server → before marking the task done, check that `/opt/services/glance/config/glance.yml` is up to date: bookmarks URLs, monitor entries, Reference page. Update if anything is missing or stale.

### End of every session:
1. Append to the project's **Sessions** section (latest first): date, what was requested, what was done
2. Update **Change Log** table: date / requested / changed / files
3. Update frontmatter if status/tech/url/server changed
4. The Stop hook auto-writes a timestamp to `99 Daily/YYYY-MM-DD.md`
5. PostCompact hook auto-writes structured entries on context compaction

### Rule: NEVER skip logging
Even if the session is short. Even if just answering a question. Log it.

## All Code Projects Location
`/Users/ai_leed/Documents/Projects/Oliver/` — this is where all code lives on disk.

## Key Facts
- Vadym = developer at Oliver Agency, building internal tools and client solutions
- Stack preferences: Python/FastAPI for backends, Docker for deployment, vanilla JS+Tailwind or React for frontends
- Language for notes: **English**
- Date format: **YYYY-MM-DD** everywhere
- Credentials are NOT tracked in vault git — stored at `~/.secrets/` locally
  - `~/.secrets/mailgun.env` — Mailgun shared infra defaults
  - `02 Areas/credentials.md` is gitignored (iCloud-only, never pushed to GitHub)

## Two-Tier Daily Log System

The system maintains **two separate daily log streams** — do not confuse them:

| Location | Written by | Read by | Purpose |
|----------|-----------|---------|---------|
| `~/.claude/memory-compiler/daily/YYYY-MM-DD.md` | `flush.py` (SessionEnd hook) | `compile.py` (nightly) | Source material for wiki compilation |
| `99 Daily/YYYY-MM-DD.md` | `obsidian-session-log.py` (Stop hook) | Human (you) | Human-readable session log |

`compile.py` reads ONLY from `memory-compiler/daily/`. It never reads `99 Daily/`.
Both logs cover the same sessions but in different formats.

## raw/ Inbox — How to Use

Drop any source material into `raw/` and say "compile raw":
- Articles, PDFs, transcripts, research notes
- Screenshots of config files or error messages (describe them as text)
- Architecture diagrams (describe as text)

Claude will extract knowledge into the correct `wiki/` folder, update `_index.md`, and move the file to `raw/_processed/`.

**SessionStart auto-detection:** At the start of each session, Claude checks `raw/*.md` for unprocessed files. If any exist, it will notify and offer to process them automatically — no need to say "compile raw" manually.

**Do NOT put credentials or sensitive data in raw/.**

## Multi-Device Setup

When setting up a new machine, run this sequence:
```bash
# 1. Clone memory-compiler
git clone <repo> ~/.claude/memory-compiler

# 2. Copy scripts from vault (they sync via iCloud)
# Scripts live in vault at: 00 Automation/ (if set up)
# OR copy from another machine's ~/.claude/

# 3. Install dependencies
cd ~/.claude/memory-compiler && uv sync

# 4. Create ~/.secrets/ with credentials
mkdir -p ~/.secrets
# Copy mailgun.env and other secrets from 1Password / secure source

# 5. Register LaunchAgents (edit paths for new machine username first)
cp ~/path/to/LaunchAgents/*.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.claude.memory-compiler.plist
launchctl load ~/Library/LaunchAgents/com.vadym.icloud-dedup.plist

# 6. Update settings.json hooks (replace ai_leed with new username)
sed -i '' 's|/Users/ai_leed/|/Users/NEW_USERNAME/|g' ~/.claude/settings.json
```

**Note:** All hook commands in `settings.json` use hardcoded `/Users/ai_leed/` paths.
When working on a different machine, update these paths. A machine-agnostic setup
(using `$HOME`) is a future improvement.

## Wiki System — You Are the Librarian

`wiki/` is YOUR domain. You write and maintain everything in it. I rarely edit wiki files directly.

### Vault Structure (3 zones)

| Zone | Path | Owner | Purpose |
|------|------|-------|---------|
| Inbox | `raw/` | Me (human) | Dump source material here — articles, PDFs, transcripts |
| Wiki | `wiki/` | You (LLM) | Compile, maintain, cross-link all knowledge |
| Output | `output/` | You (LLM) | Query results, reports, slide decks |

### Wiki File Structure (Karpathy RAG format)

```
wiki/
├── _master-index.md        ← LLM's table of contents — ALWAYS keep current
├── log.md                  ← Append-only build log
├── {topic}/                ← One folder per knowledge topic
│   ├── _index.md           ← Lists all articles in this topic
│   └── {article}.md        ← Individual knowledge article
├── concepts/               ← Session-derived atomic knowledge
├── connections/            ← Cross-cutting insights
└── qa/                     ← Filed query answers
```

### Navigation Pattern (3 hops — no RAG needed)

When answering any question against the wiki:
1. Read `wiki/_master-index.md` — "what topics exist?"
2. Read that topic's `_index.md` — "what articles exist?"
3. Read the specific 1–3 articles
4. Synthesize the answer

### Compiling (when I say "compile" or add files to raw/)

For each file in `raw/`:
1. Read it and identify the core topic
2. Create or find the right topic subfolder in `wiki/`
3. Write a wiki article with key takeaways and `[[wikilinks]]` to related concepts
4. Update that topic's `_index.md`
5. Update `wiki/_master-index.md`
6. If raw file spans multiple topics — create articles in both, cross-link
7. Move processed file to a `raw/_processed/` subfolder (don't delete)

### Article Conventions

- File names: lowercase with hyphens (`ai-agent-patterns.md`)
- Always use `[[wikilinks]]` when referencing other notes
- Keep articles concise — bullet points over paragraphs
- Every article must have a `## Key Takeaways` section
- Every article must link to at least 2 other articles

### Auditing (when I say "audit" or "lint")

Review the wiki for:
- Inconsistent or contradictory information across articles
- Missing cross-links between related concepts
- Orphan articles (no one links to them)
- Topics mentioned but without dedicated articles
- Suggest 3–5 new articles that would strengthen the knowledge base
- **Do NOT make changes without confirmation — just report**

### Q&A Auto-Save Protocol

When answering a **complex technical question** during a session (debugging, architecture, how-to), save the answer to `wiki/qa/`:

1. Create `wiki/qa/{topic-slug}.md` with the question as H1, answer as body, `## Key Takeaways` section, and `## Related` wikilinks
2. Add entry to `wiki/qa/_index.md`
3. Update `wiki/_master-index.md` count

**Threshold for saving:** The answer involves non-obvious reasoning, debugging steps, or knowledge that would take >5 minutes to rediscover. Don't save answers to questions with obvious answers.

**Slug format:** `{problem}-{resolution}.md` e.g. `fastapi-cors-docker-fix.md`, `azure-ad-403-wrong-flow.md`

### Auto-compilation from Sessions

Sessions are captured automatically via Claude Code hooks and compiled to `wiki/concepts/`, `wiki/connections/`, and `wiki/qa/` after 21:00 (9 PM).

**Query command:**
```bash
cd ~/.claude/memory-compiler && uv run python scripts/query.py "your question"
```

**Manual compile:**
```bash
cd ~/.claude/memory-compiler && uv run python scripts/compile.py
```

## Automation Hooks
Five hooks fire automatically via Claude Code settings (global, from any project):

| Event | Script | Purpose |
|-------|--------|---------|
| **SessionStart** | obsidian-session-start.py | Loads project note + pending commands + check raw/ inbox |
| **SessionStart** | memory-compiler/hooks/session-start.py | Injects wiki/index.md + current-state.md + recent daily log |
| **PreCompact** | memory-compiler/hooks/pre-compact.py | Captures transcript → saves current-state.md → spawns flush.py |
| **SessionEnd** | memory-compiler/hooks/session-end.py | Captures session transcript → knowledge flush → daily log |
| **Stop** | time_tracker.py + cc-collector.py + obsidian-session-log.py | Time tracking + CC dashboard + daily note timestamp |

**Data flow:**
```
PreCompact → flush.py (background) → daily/YYYY-MM-DD.md
           → current-state.md ← next SessionStart reads this → context restored

Session ends → SessionEnd hook → flush.py → daily/YYYY-MM-DD.md
                                      ↓ (after 21:00)
                              compile.py → wiki/concepts/ (Obsidian vault)
```

## MCP Servers

| MCP | When to use |
|-----|-------------|
| `context7` | Live docs for FastAPI, Next.js, React, etc. — use instead of searching Google |
| `basic-memory` | Store a decision or insight mid-session (`create_entities`) / recall from past sessions (`search_nodes`) — writes `.md` files directly into this vault |
| `postgres` | Direct SQL queries to project DBs without writing scripts |
| `redis` | Redis operations for cc-dashboard, ai-cost-tracker, video-accessibility |
| `sequential-thinking` | Complex multi-step architectural decisions |

## My Role
- Log work clearly so context is never lost between sessions
- Keep notes accurate and up-to-date — no stale info
- Link related projects with [[wikilinks]]
- Never create a note for something already documented — update existing notes
- Use tag taxonomy consistently
- Move completed/abandoned projects to 04 Archive