Vault Organization (Hermes Agent)

This user's Obsidian vault is at /mnt/c/Users/keila/Mateus/vault. It serves as both a personal knowledge base and a workspace for the Hermes Agent to store config docs, session logs, and project context.

The vault was previously organized for the Jarvis/OpenCode multi-agent system. Some folders and INDEX references may be stale.

Actual Vault Structure

```vault/
├── INDEX.md                       # Main entry point (keep updated)
├── README.md                      # Vault description
├── wiki-links.md                  # Wiki link syntax reference
├── Changelog-*.md                 # Reorganization records
│
├── Cursos/                        # Active courses — light notes + materials
│   ├── INDEX.md                   #   Master course index
│   ├── Cursos de AI.md            #   AI course portal
│   └── {course-slug}/             #   One dir per course (kebab-case)
│       ├── INDEX.md               #   Course overview, progress bar
│       ├── NN-module-topic/       #   Per-module/aula notes
│       │   ├── INDEX.md           #     Module study note
│       │   ├── solucionador-problemas.md  #     Standalone guide notes
│       │   └── materiais/         #     PDFs, XLSX, DOCX, MP4, PPTX
│       ├── presentes/             #   Bonus materials from the course
│       └── compartilhados/        #   Cross-cutting resources
│
├── escola/                        # Academic studies
│   ├── index.md
│   └── física/                    #   Physics study notes
│
├── knowledge/                     # Consolidated knowledge (9 subdirs)
│   ├── agentes-ia/                #   AI agent courses + YouTube (16 notes)
│   ├── ia-express/                #   Deep notes — Curso IA Express (3 notes)
│   ├── design/                    #   Design, Figma, web design (4 notes)
│   ├── javascript-trilha/         #   JS course materials (17 notes)
│   ├── mcp/                       #   MCP / Model Context Protocol (1)
│   ├── pkm/                       #   Personal Knowledge Mgmt / Obsidian (2)
│   ├── projetos/                  #   Internal project docs (1)
│   ├── youtube/                   #   Standalone YouTube videos (1)
│   ├── UI-UX-Design-MasterNote.md
│   ├── design-system-gerando-programadores.md
│   ├── javascript-course-ifc-structure.md
│   ├── lessons-learned-ifc-integration.md
│   └── project-overview-gerando-programadores.md
│
├── agents/                        # Agent definitions — unified (15 notes)
│   ├── hermes-gateway-config.md
│   ├── agent-registry-jarvis.md
│   ├── coder-improved.md, debugger.md, ui-designer.md, vault-organizer.md
│   ├── frontend-architect.md, backend-pro.md, database-architect.md
│   ├── security-auditor.md, skill-crafter.md, test-automator.md
│   ├── azure-ml-ops.md, brand-designer.md, file-structure-specialist.md
│   └── ui-ux-design/
│
├── sessions/                      # Session logs (was ai-actions/)
│   ├── log.md
│   └── YYYY-MM-DD-*.md
│
├── projects/                      # Project notes and SPECs
│   ├── INDEX.md
│   ├── gerando-programadores/
│   ├── pesca/
│   └── frontend-gerando-programadores/
│
├── guides/                        # How-to guides (git, agent creation)
├── journal/                       # Daily entries
├── research/                      # Raw ideas and experiments
├── skills/                        # Skill definitions
├── Templates/                     # Note templates
├── opencode/                      # OpenCode CLI config reference
├── Jarvis/                        # Historical archive (preserve, cross-link)
└── ...

Key Principles

Document System Config Changes

When configuring Hermes Agent (gateway, MCP servers, tools, env vars, etc.):

Create or update a note under agents/ (e.g., agents/hermes-gateway-config.md)
Record: exact env vars set, config file changes, reproduction steps, pitfalls encountered
Cross-link to related notes (MCP integrations, etc.)

Auto-commit to git after ANY vault modifications. Use descriptive commit messages in Portuguese describing what changed:

cd /mnt/c/Users/keila/Mateus/vault
git add -A
git commit -m "Reorganiza pasta Cursos — estrutura limpa, MDs bonitos e notas de estudo"
# Better than generic "update vault" — be specific about the scope

If git commit fails with "Author identity unknown", set the repo-level user first (the repo may not have global git config):

git config user.name "Mateus2411"
git config user.email "mateushenriquedasilva2411@gmail.com"

Cross-Link Everything for Graph Health

Every note should have at least one incoming wiki-link
Use descriptive display text: [[note|Useful Description]]
Tag consistently: lowercase, hyphenated (#hermes/gateway, #projects/pesca)
Hubs (INDEX.md, agent registry) should link to all their children; children should link back

Keep INDEX.md Grounded in Reality

INDEX.md must reflect the actual folder structure, not an aspirational one
Remove references to folders that don't exist (e.g., inbox/, ai-memory/)
Update whenever folders are added, removed, or renamed

Vault Migration (completed 2026-05-10)

The following migrations were done. Most old paths are now fully absorbed into the new locations below; exceptions are noted.

✅ YouTube/ → merged into knowledge/ (agentes-ia, mcp, pkm, youtube)
✅ Jarvis/Agents/ → merged agent definitions into agents/ (unified: 15 total)
✅ ai-actions/ → renamed to sessions/
Jarvis/MCP/ → reference in agents/hermes-gateway-config.md or appropriate config note
Jarvis/Skills/ → these are OpenCode skills, keep in opencode/
Jarvis/Vault-Health-Reports/ → no longer needed (was for old Jarvis system)
Preserve Jarvis/ as an archive folder with cross-links from the new locations

Note on Cursos/: This folder remains a top-level directory for active course materials and light notes. It is NOT merged into knowledge/. The two work as a dual layer:

Cursos/{course}/ — materials (PDFs, XLSX, MP4), presents, per-class INDEX
knowledge/{course-slug}/ — deep study notes, methodology breakdowns, insights

Both layers cross-link to each other for graph health.

When performing future migrations of remaining Jarvis content: use the same protocol (see below → When Reorganizing).

Vault Health Audit

Periodically (or when user says "revisa a vault") run a full health check:

Check for empty directories: List all dirs with terminal find . -type d -empty under the vault path. Remove empty legacy folders (e.g., migrated ai-actions/, YouTube/, Cursos/ old structure after reorganization).
Check for duplicate files: Look for same-named files across directories — particularly PDFs that may exist in both knowledge/{course}/ and Cursos/{course}/materiais/ or presentes/. The canonical copy lives in Cursos/; remove from knowledge/.
Verify INDEX.md counts match reality: The main INDEX.md lists file counts per knowledge subfolder. Compare against mcp_obsidian_list_directory output. Common discrepancies:
- "Agentes de IA (11 notas)" → actually 16 → update
- "JavaScript (3 notas)" → actually 17 → update
- "Design (4 notas)" but only 3 listed → add missing
- "YouTube (2 notas)" but only 1 → correct
Verify structure tree matches reality: The ASCII tree in INDEX.md should list every top-level folder. Missing folders (e.g., Cursos/, escola/) break navigation.
Update timestamps: *Última atualização: 2026-05-10* → update to today's date. Same for projects/INDEX.md and README.md.
Check cross-links: Ensure new additions (Cursos, solucionador-problemas, etc.) appear in the Atalhos Rápidos table and have backlinks from their parent notes.
Commit after audit: Single git add -A && git commit -m "Revisão geral da vault: ..." with a bullet list in the message body if many changes.

When Reorganizing

Protocol (verified 2026-05-10, 25 wikilinks fixed, 28 notes tagged):

Survey first: Read INDEX.md for intended structure, then list actual directories with obsidian_list_directory — the gap between intended and actual is what to fix.
Plan in phases: Create a todo list with discrete steps. Order: create destination dirs → move files → fix links → add tags → update INDEX/README.
Create destination dirs first using mcp_filesystem_create_directory (the raw filesystem path under the vault, e.g. /mnt/c/Users/keila/Mateus/vault/knowledge/agentes-ia).
Move files in batches with obsidian_move_note. Group related moves together. The tool auto-creates intermediate paths. Verify with obsidian_list_directory on source dirs afterward — they should be empty.
Fix broken wiki-links systematically — this is the most critical step and the most likely to be missed:
- After bulk moves, run search_files with regex pattern for the old path prefix (e.g., YouTube-Learnings/ or design-basics)
- Fix with patch tool, one file at a time, using the exact old → new text
- Re-run search_files to verify zero remaining broken links
- A SECOND PASS is almost always needed — the first search reveals more broken links in notes you didn't expect
Delegate bulk link-fixing when there are 15+ broken links: use delegate_task with explicit mapping of every old → new path. The sub-agent can handle the repetitive patching while you continue with other phases.
Add tags with obsidian_manage_tags after moves are complete. Use class-level tags (#agentes-ia, #design, #pkm, #mcp) that match the destination directory name — this makes graph views filterable by category.
Update INDEX.md and README.md last, after all files are in their final locations. Include all subdirectories with file counts. Add a changelog note explaining what moved where and how many links were fixed.
Save to memory: Store the reorganization fact so future sessions don't look for notes under old paths.

Organizing Course Folders (Cursos/)

When the user asks to organize or create course folders:

Use the dual-layer pattern:
- Cursos/{course-slug}/ — light INDEX.md notes + physical materials (PDFs, XLSX, MP4, PPTX, DOCX)
- knowledge/{course-slug}/ — deep study notes with full methodology, prompts, transcripts, insights
- Cross-link both layers with wiki-links
Ingest from external course links first: When the user shares external resources (Lovable apps, companion sites, PDFs, guide pages):
- Open each link with browser_navigate → extract key content (frameworks, prompts, methodology)
- For accordion/collapsible pages, click elements before snapshot
- For unavailable video transcripts, rely on companion sites and materials
- Cross-reference extracted content across sources to avoid duplication
- Create dedicated study notes (e.g., solucionador-problemas.md) for standalone guides
- Add a "Material Extra" section in the corresponding aula INDEX.md with external URLs + internal links

Course directory structure:

Cursos/{course-slug}/
├── INDEX.md                    # Course overview with progress bar
├── 01-module-topic/            # Per-module/aula, numbered
│   ├── INDEX.md                # Module note: summary, tools, checklist, extra links
│   └── materiais/              # Original PDFs, XLSX, MP4, etc.
├── 02-module-topic/
│   ├── INDEX.md
│   └── materiais/
├── presentes/                  # Bonus material from the course
└── compartilhados/             # Cross-module resources

INDEX.md conventions for course notes:
- Progress bar: ▓▓▓▓░░░░░░ 40% (2/4 aulas) — ASCII visual
- Status badges: ✅ completo, 🔴 pendente (assistir replay), ⏳ futura
- Tables: course info (instrutor, data, link), aula schedule, material list
- Checklists: - [x] for completed, - [ ] for pending
- Frontmatter: date, instrutor, status, tags, title
- Backlinks: every aula note links back to the course INDEX and to knowledge/
Handling "presentes" (bonus materials): Collect all bonus/gift materials into a presentes/ folder at course level, not per-aula. Link them from the aula INDEX.md and from course INDEX.md.
Naming conventions:
- Course folder: kebab-case (ia-express, flux-academy-web-design)
- Module folders: {NN}-{topic-slug} (01-ferramentas-ia, 02-analise-dados)
- INDEX.md always in every folder for navigation
- Avoid special chars in filenames (accented characters) for WSL/Windows compatibility
Connection to vault INDEX: After creating/restructuring a course, update:
- Cursos/INDEX.md — the master course index
- Cursos/Cursos de AI.md (if applicable) course portal
- INDEX.md — main vault index (add link in Atalhos Rápidos if missing)
- knowledge/{course-slug}/ notes → add backlinks to Cursos/{course-slug}/

Triggers

User says "organize my vault", "clean up", "reorganize", "structure notes"
User says "document this in the vault too"
User says "revisa a vault" or "revisa minha vault" — run the Vault Health Audit
User says "reorganiza minha vault"
After significant Hermes config changes, offer to document in the vault

Pitfalls

Broken wiki-links require MULTIPLE passes. After moving files, run search_files for the old path prefix → fix → search again → fix more. Each pass uncovers notes you didn't realize had cross-references. In the 2026-05-10 reorganization, it took 4 search-fix cycles to clear all ~25 broken links.
search_files regex must match the exact wikilink syntax. Obsidian wiki-links can be [[Path/Note]] or [[Path/Note|Display Text]]. Search for the bare path prefix without brackets to catch both forms.
delegate_task for bulk fixes is faster but verify afterward. The sub-agent may miss edge cases (mixed case in filenames, links in code blocks). Always run a final search_files yourself.
Empty directories persist after obsidian_move_note. Harmless but can cause confusion. Optionally delete with mcp_filesystem_delete_directory.
Tags accumulate with obsidian_manage_tags — it appends, doesn't replace. Some notes already have 30+ tags from the JARVIS era.
Wiki-link alias (|) conflicts with markdown table syntax. When writing [[arquivo.pdf|Alias]] inside a | col1 | col2 | table, the pipe | in the wiki-link breaks the table. mcp_obsidian_write_note may write \\\\| literally if you try escaping with \\|. Fix: either (a) omit the alias inside tables (use bare [[arquivo.pdf]] and put the display text in an adjacent column) or (b) write the table without wiki-link aliases and add them after with patch. Verify by reading the note back after writing.
mcp_filesystem_create_directory fails on nested dirs. This MCP tool only creates one level at a time and errors if the parent doesn't exist. Create deep paths with terminal + mkdir -p instead.
The patch tool has no linter for .md files. Verify patched content by reading the note afterward, especially multiline replacements.

Reference Files

references/multi-source-course-notes.md — Workflow for creating vault notes from multiple independent sources (video + PDF + website): parallel extraction, content synthesis, note structure conventions, git commit pattern.

vault-org

SKILL.mdskills/vault-org/SKILL.md