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: /Volumes/SSD/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

### 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
`/Volumes/SSD/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 in the vault — stored at `~/.secrets/` locally

## 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**

### 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
Six hooks fire automatically via Claude Code settings (global, from any project):

| Event | Script | Purpose |
|-------|--------|---------|
| **SessionStart** | obsidian-session-start.py | Loads project note + pending commands |
| **SessionStart** | memory-compiler/hooks/session-start.py | Injects wiki/index.md + recent daily log |
| **PostCompact** | obsidian-postcompact.py | Haiku writes structured session entries to project note + daily note |
| **PreCompact** | memory-compiler/hooks/pre-compact.py | Captures transcript before compaction → knowledge flush |
| **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:**
```
Session ends → SessionEnd hook → flush.py (background) → daily/YYYY-MM-DD.md
                                      ↓ (after 21:00)
                              compile.py → wiki/concepts/ (Obsidian vault)
```

## 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