AI agent guidance

This file provides ai agent guidance when working with files in this repository.

CRITICAL: This is an Obsidian Vault

This directory is managed by Obsidian (obsidian.md), a knowledge base and note-taking application.

⚠️ IMPORTANT: Obsidian uses its own "Obsidian Flavored Markdown" which extends standard Markdown with proprietary features. Many syntax elements will NOT work in standard Markdown editors or GitHub. When working with files in this vault:

Do NOT assume standard Markdown compatibility
Do NOT convert Obsidian syntax to standard Markdown unless explicitly requested
Preserve Obsidian-specific syntax (wikilinks, embeds, callouts, etc.)
Be aware that files are interconnected through Obsidian's link graph

Repository Overview

This is an Obsidian vault organized using the PARA method (Projects, Areas, Resources, Archive). It contains personal notes, knowledge management, and various documentation in German and English.

Obsidian Syntax & Features Guide

Internal Links (Wikilinks)

Obsidian uses double-bracket wikilinks instead of standard Markdown links:

[[Note Name]]              # Links to "Note Name.md"
[[Note Name|Display Text]] # Link with custom display text
[[Note Name#Heading]]      # Link to specific heading in note
[[Note Name#^block-id]]    # Link to specific block

Important: These are NOT standard Markdown links and will not work outside Obsidian.

Embedding Content

Obsidian can embed entire notes, images, PDFs, and other content using ![[]] syntax:

![[Other Note]]                    # Embeds entire note
![[Other Note#Heading]]            # Embeds specific section
![[image.png]]                     # Embeds image
![[document.pdf]]                  # Embeds PDF
![[document.pdf#page=3]]           # Embeds specific PDF page
![[audio.mp3]]                     # Embeds audio player
![[video.mp4]]                     # Embeds video player
![[Other Note#^block-id]]          # Embeds specific block

You can also embed external content:

![](https://example.com/image.jpg)  # External image

Properties (Frontmatter)

Obsidian uses YAML frontmatter for structured metadata:

---
created: 2026-02-01T09:25
updated: 2026-02-01T09:30
tags:
  - project
  - ai
status: in-progress
priority: high
author: Name
aliases:
  - Alternative Title
  - Another Name
---

Supported Property Types:

Text: Simple strings
List: Arrays of values
Number: Numeric values
Checkbox: Boolean (true/false)
Date: ISO format dates (YYYY-MM-DD)
Date & Time: ISO format (YYYY-MM-DDTHH:MM:SS)

Special Properties:

tags: Tag list (alternative to inline tags)
aliases: Alternative names for the note
cssclasses: Apply custom CSS classes
created/updated: Timestamps (managed by update-time-on-edit plugin in this vault)

Callouts (Admonitions)

Obsidian supports styled callout blocks:

> [!note]
> This is a note callout.

> [!tip] Custom Title
> This is a tip with a custom title.

> [!warning]- Foldable Callout
> This callout can be folded (starts collapsed with `-`)

> [!danger]+ Foldable Callout (Expanded)
> This callout can be folded (starts expanded with `+`)

Built-in Callout Types:

note, abstract, summary, tldr
info, todo
tip, hint, important
success, check, done
question, help, faq
warning, caution, attention
failure, fail, missing
danger, error
bug
example
quote, cite

Block References

Create references to specific blocks:

This is a paragraph. ^unique-block-id

Reference it elsewhere: ![[Note Name#^unique-block-id]]

Comments

Obsidian supports HTML-style comments that don't appear in Reading mode:

%% This is a comment %%

%%
Multi-line
comment
%%

Math (LaTeX)

Inline and block math using LaTeX:

Inline math: $e = mc^2$

Block math:
$$
\int_{a}^{b} f(x) \, dx
$$

Diagrams (Mermaid)

Obsidian bundles Mermaid.js (v11.4) and supports diagrams inside mermaid code blocks. All diagrams use the same wrapper:

```mermaid
<diagram-keyword>
    ...
```

Available Diagram Types:

Keyword	Diagram Type	Description
`flowchart` or `graph`	Flowchart	Process flows and decision trees. Directions: `TB`, `TD`, `BT`, `RL`, `LR`
`sequenceDiagram`	Sequence Diagram	Actor interactions over time
`classDiagram`	Class Diagram	OOP class structures and relationships
`stateDiagram-v2`	State Diagram	State machines and transitions
`erDiagram`	Entity Relationship	Database schemas and entity connections
`journey`	User Journey	User experience flows with satisfaction scores
`gantt`	Gantt Chart	Project timelines and task scheduling
`pie`	Pie Chart	Proportional data visualization
`quadrantChart`	Quadrant Chart	Four-quadrant positioning (e.g. priority matrix)
`requirementDiagram`	Requirement Diagram	Requirements and traceability
`gitGraph`	Git Graph	Git branching, commits, and merges
`C4Context`	C4 Diagram	Software architecture (C4 model). Also: `C4Container`, `C4Component`, `C4Deployment`
`mindmap`	Mindmap	Hierarchical mind mapping
`timeline`	Timeline	Sequential event visualization
`zenuml`	ZenUML	Sequence-based UML diagrams
`sankey-beta`	Sankey Diagram	Flow and proportion visualization
`xychart-beta`	XY Chart	Line/bar charts on cartesian coordinates
`block-beta`	Block Diagram	Block and module diagrams
`packet-beta`	Packet Diagram	Network packet structure
`kanban`	Kanban Board	Workflow task boards
`architecture`	Architecture	System architecture layouts

Example (Flowchart):

```mermaid
flowchart TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
```

Example (Sequence Diagram):

```mermaid
sequenceDiagram
    Alice->>Bob: Hello Bob
    Bob-->>Alice: Hi Alice
```

Example (Gantt Chart):

```mermaid
gantt
    title Project Plan
    section Phase 1
    Task A :a1, 2026-01-01, 30d
    Task B :after a1, 20d
```

Example (Pie Chart):

```mermaid
pie title Pets
    "Dogs" : 40
    "Cats" : 35
    "Fish" : 25
```

Note: Diagram types with -beta suffix are experimental and may change in future Mermaid versions. Some very new types (e.g. radar, treemap) may not yet be available in the Mermaid version bundled with Obsidian.

Code Blocks

Standard Markdown code blocks with syntax highlighting:

```python
def hello():
    print("Hello World")
```

```js
console.log("JavaScript");
```

Tables

Standard Markdown tables:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Task Lists

Checkbox tasks with Obsidian Tasks plugin extensions:

- [ ] Uncompleted task
- [x] Completed task
- [>] Forwarded task
- [<] Scheduled task
- [!] Important task
- [-] Cancelled task
- [/] In progress task
- [?] Question task

Tasks Plugin Syntax (available in this vault):

- [ ] Task with due date 📅 2026-02-01
- [ ] Task with scheduled date ⏳ 2026-02-01
- [ ] Task with start date 🛫 2026-02-01
- [ ] Task with completion date ✅ 2026-02-01
- [ ] Task with recurrence 🔁 every week
- [ ] Task with priority ⏫ (high), 🔼 (medium), 🔽 (low)

Folding

Headings and lists can be folded in Obsidian:

# Heading can be folded

- List item
  - Nested item (can be folded)
  - Another nested item

HTML Support

Obsidian supports inline HTML:

<div style="color: red;">Styled text</div>
<details>
  <summary>Collapsible section</summary>
  Hidden content
</details>

Footnotes

Standard Markdown footnotes:

This is a sentence with a footnote.[^1]

[^1]: This is the footnote content.

Highlights

==Highlighted text==

Advanced Formatting

~~Strikethrough~~
**Bold**
*Italic*
***Bold and Italic***

Canvas Files

Obsidian supports .canvas files for visual organization (JSON format):

Not standard Markdown files
Visual mind-mapping and connection tool
Binary/JSON format

Dataview Plugin

This vault has the Dataview plugin which allows querying notes:

```dataview
TABLE file.ctime as Created, file.mtime as Modified
FROM "PARA/1 Project"
WHERE contains(tags, "active")
SORT file.mtime DESC
```

Note: Dataview uses its own query language (DQL) and is specific to Obsidian vaults with the plugin.

Bases (Core Plugin)

Bases is a core plugin (v1.9+) that creates database-like views of your notes using their frontmatter properties. Unlike Dataview, Bases requires no programming knowledge and uses a visual UI plus .base files.

`.base` File Format

Bases uses YAML-formatted .base files with these sections:

filters:
  and:
    - file.hasTag("project")
    - file.inFolder("PARA/1 Project")
formulas:
  days_until_due: due - today()
  is_overdue: due < today()
properties:
  status:
    displayName: "Status"
summaries:
  priority:
    formula: values.filter(value == "high").length
views:
  - type: table
    name: "Active Projects"
    filters:
      and:
        - status == "active"
    order:
      - property: due
        direction: asc
    groupBy:
      property: status
      direction: asc
    limit: 50

View Types

Table (v1.9+): Files as rows, properties as columns. Supports keyboard navigation, cell selection, copy/paste, summaries at column bottoms.
Cards (v1.9+): Grid layout with optional cover images. Configurable card size and image fit.
List (v1.10+): Bulleted or numbered lists with nested property display.
Map (v1.10+): Files as pins on an interactive map (requires Maps plugin).

Community plugins can add additional view types.

Embedding Bases

Embed as file reference:

![[MyBase.base]]              # Embeds default view
![[MyBase.base#View Name]]    # Embeds specific view

Embed as inline code block (YAML inside a base code block):

```base
filters:
  and:
    - file.hasTag("example")
views:
  - type: table
    name: Table
```

Property Namespaces

Three types of properties are available in formulas and filters:

Note properties: Frontmatter values, accessed as property_name (e.g., status, due)
File properties: Metadata available for all files:
- file.name, file.basename, file.path, file.folder, file.ext
- file.size, file.ctime, file.mtime
- file.links, file.tags, file.properties, file.backlinks
Formula properties: Calculated values defined in the formulas section, accessed as formula.name

The `this` Context

In base main view: this refers to the base file itself
In embedded base: this refers to the embedding note
Enables context-aware queries like file.hasLink(this.file)

Key Functions

Global: date(), duration(), file(), link(), list(), if(), now(), today(), number(), max(), min(), image(), icon(), html(), escapeHTML()

File: file.hasTag(), file.hasLink(), file.inFolder(), file.hasProperty(), file.asLink()

Date: date.format(), date.relative(), date.date(), date.time() + fields: year, month, day, hour, minute, second

String: contains(), split(), replace(), slice(), lower(), upper(), trim(), startsWith(), endsWith(), title(), repeat(), reverse()

Number: abs(), ceil(), floor(), round(), toFixed()

List: filter(), map(), reduce(), sort(), join(), unique(), flat(), reverse(), slice(), contains()

Link: asFile(), linksTo()

Object: keys(), values(), isEmpty()

Any: isTruthy(), isType(), toString(), isEmpty()

Operators

Arithmetic: +, -, *, /, %
Comparison: ==, !=, >, <, >=, <=
Boolean: !, &&, ||
Date arithmetic: date + "1d", date - "2h" (duration units: y, M, d, w, h, m, s)

Filter Conjunctions

and: All conditions must be true
or: Any condition can be true
not: No conditions may be true

Filters can be set globally (applies to all views) or per-view.

Built-in Summary Functions

Used for aggregation at column bottoms or group headers:

Category	Functions
Number	Average, Sum, Min, Max, Range, Median, Stddev
Date	Earliest, Latest, Range
Boolean	Checked, Unchecked
Any	Empty, Filled, Unique

Custom summary formulas receive values containing all property values across results.

Creating a Base

Command Palette: Bases: Create new base or Bases: Insert new base
File Explorer: Right-click folder > "New base"
Ribbon: "Create new base" button

Bases vs Dataview

Bases is the official core plugin replacement for many Dataview use cases. Key differences:

Bases uses a visual UI; Dataview requires DQL/JS syntax
Bases stores configuration in .base files; Dataview uses inline code blocks
Bases supports interactive editing (click cells to edit properties); Dataview is read-only
Bases supports multiple view types (table, cards, list, map); Dataview supports table, list, task
Dataview supports inline properties; Bases does not
Both can coexist in the same vault

Vault Structure

PARA Organization

The vault follows Tiago Forte's PARA methodology (see PARA/PARA.md for detailed explanation):

1 Project (PARA/1 Project/): Active, short-term projects with specific goals
- Examples: Job applications, AI experiments, specific research tasks
- Projects have defined endpoints
2 Area (PARA/2 Area/): Long-term responsibility areas requiring continuous attention
- Examples: Career, Family, Health, Housing, Finances, Insurance
- No defined endpoints; require regular maintenance
3 Resource (PARA/3 Resource/): Topics and knowledge collections for potential future use
- Examples: AI/KI research, photography, home automation, security
- Reference material without immediate action required
4 Archive (PARA/4 Archive/): Inactive items from other categories kept for future reference

Notes Organization

_Notes/Daily: Daily notes with frontmatter (created/updated timestamps)
_Notes/Weekly: Weekly notes (enabled via periodic-notes plugin)
_Notes/Quarter: Quarterly notes (enabled via periodic-notes plugin)

Other Directories

_assets: Attachment storage (configured in .obsidian/app.json)
Incoming.md: Quick capture for links and temporary items
TODOs.md: Task tracking with checkboxes (short-term and long-term sections)

Key Plugins

Core Plugins

Bases (v1.9+): Database-like views of notes using frontmatter properties. Supports table, cards, list, and map views. Uses .base files with YAML syntax.

Community Plugins

Active community plugins (from .obsidian/community-plugins.json):

obsidian-tasks-plugin: Task management with due dates, recurring tasks, and filtering
dataview: Query and display data from notes
periodic-notes: Daily, weekly, and quarterly note automation
calendar: Calendar view integration
obsidian-kanban: Kanban board support
obsidian-icon-folder: Folder icons
folder-note-plugin: Folder notes capability
update-time-on-edit: Automatic timestamp updates
obsidian-pandoc: Document export via Pandoc
obsidian-plantuml: PlantUML diagram support
tag-wrangler: Tag management
waypoint: Folder overview generation
emoji-shortcodes: Emoji support

File Conventions

Frontmatter

Notes use YAML frontmatter with timestamps:

---
created: YYYY-MM-DDTHH:MM
updated: YYYY-MM-DDTHH:MM
---

Language

Content is primarily in German
Some technical documentation and code-related content in English
File names may be in either language

File Naming

No strict naming convention
Use descriptive names
Spaces in filenames are common

Working with This Vault

Adding New Content

New projects go in PARA/1 Project/
New areas of responsibility in PARA/2 Area/
Reference material and knowledge in PARA/3 Resource/
Move completed/inactive items to PARA/4 Archive/

Tasks

Use TODOs.md for general task tracking
Use the Tasks plugin syntax for advanced task management
Tasks can be embedded in any note using - [ ] checkbox syntax

Attachments

Place attachments in ./attachments (configured attachment folder)
Link updates are automatic when moving files (alwaysUpdateLinks: true)

Daily Notes

Daily notes are in _Notes/Daily/ with format YYYY-MM-DD.md
Created automatically via periodic-notes plugin
Use for journal entries, meeting notes, daily logs

PARA Method Guidelines

When to Create a Project

Has a specific goal or outcome
Will eventually be completed
Requires active work

When to Create an Area

Requires ongoing attention
No defined endpoint
Part of ongoing responsibilities

When to Create a Resource

Reference material for potential future use
Interesting topics to explore later
No immediate action required

When to Archive

Projects are completed
Areas are no longer relevant
Resources are no longer useful but worth keeping

Important Notes

About This Vault

The vault is NOT a git repository
Readable line length is disabled (full width editor)
The update-time-on-edit plugin automatically updates the updated timestamp in frontmatter
Attachment folder is configured to ./attachments
Link updates are automatic when moving files (alwaysUpdateLinks: true)

Working with Obsidian Syntax

DO:

Use [[wikilinks]] for internal links
Use ![[embed]] syntax for embedding content
Preserve existing frontmatter properties
Use callouts for important information: > [!note]
Use tags in the format #tag or #nested/tag
Reference blocks with ^block-id and embed with ![[#^block-id]]
Use Dataview queries when querying multiple notes
Keep HTML comments with %%comment%% syntax
Use Tasks plugin syntax for task management
Use Bases for database-like views of notes (.base files or inline base code blocks)

DON'T:

Convert [[wikilinks]] to standard Markdown links [text](url) unless explicitly requested
Remove or modify ![[embeds]] syntax
Change Obsidian callouts to standard blockquotes
Remove frontmatter properties without understanding their purpose
Use standard Markdown link syntax for internal vault links
Assume files with the same name in different folders are the same (Obsidian handles this)
Break existing block references or embeds
Modify .canvas files manually (they're managed by Obsidian)
Modify .base files without understanding their YAML structure (break views/filters)

File Operations

Creating New Notes:

Add appropriate frontmatter with created and updated timestamps
Use descriptive names (spaces are allowed)
Place in correct PARA category
Consider adding relevant tags

Modifying Existing Notes:

Preserve existing frontmatter structure
Don't modify created timestamp (only updated changes)
Be careful with embedded content - changes may affect other notes
Check for backlinks before renaming or moving notes

Linking Notes:

Prefer [[Note Name]] over [[folder/Note Name]] when unambiguous
Use aliases in frontmatter for alternative note names
Use | for custom display text: [[Note Name|Display]]
Link to headers: [[Note#Header]]
Link to blocks: [[Note#^block-id]]

Plugin-Specific Features

Tasks Plugin (obsidian-tasks-plugin):

Supports extended checkbox types: [x], [>], [<], [!], [-], [/], [?]
Use emoji syntax for metadata: 📅 due, ⏳ scheduled, 🛫 start, ✅ done, 🔁 recurrence, ⏫🔼🔽 priority
Can query tasks across vault with code blocks

Dataview Plugin:

Can query and display note metadata
Uses DQL (Dataview Query Language)
Runs queries in code blocks with dataview language
Can create dynamic tables, lists, and task lists

Bases Plugin (core):

Creates database-like views of notes from frontmatter properties
Uses .base files (YAML format) or inline base code blocks
Supports table, cards, list, and map view types
Formulas and filters use a built-in expression language (not DQL)
Embed with ![[File.base]] or ![[File.base#View Name]]
Properties are editable directly in table cells
Supports grouping, sorting, and summary aggregations
this context changes based on where the base is embedded

Periodic Notes Plugin:

Manages daily notes in _Notes/Daily/
Manages weekly notes in _Notes/Weekly/
Manages quarterly notes in _Notes/Quarter/
Uses automatic naming conventions

PlantUML Plugin:

Supports PlantUML diagrams in code blocks
Use language identifier plantuml

Obsidian Graph

Obsidian maintains a graph of note connections via wikilinks
Breaking links affects the graph structure
Orphaned notes (no incoming/outgoing links) may be intentional
Backlinks are automatically tracked

Search and Queries

Obsidian has powerful search:

Search is case-insensitive by default
Can search in file names, content, tags, properties
Supports regex, boolean operators, and field-specific searches
Dataview queries can create dynamic lists

dhcgn/Obsidian_AI_AGENT_GUIDANCE.md