List all markdown notes in the vault, optionally scoped to a folder.

Args: folder: Subfolder to list notes from (relative to vault root). If empty, lists all notes in the vault.

Returns: Newline-separated list of note paths relative to vault root.

List subfolders in the vault, optionally scoped to a parent folder.

Skips hidden directories and empty folders.

Args: folder: Parent folder to list subfolders from (relative to vault root). If empty, lists top-level vault folders.

Returns: Newline-separated list of folder paths relative to vault root.

Read a note from the vault.

Args: note_path: Path to the note relative to vault root max_lines: Optional maximum number of lines to return. If omitted, returns the full note.

Returns: Note content (possibly truncated) or error description

Get the frontmatter metadata from a note as JSON.

Args: note_path: Path to the note relative to vault root

Returns: JSON string with metadata or error description

Search notes containing the query text (case-insensitive).

Args: query: Text to search for folder: Optional subfolder to limit search scope context_lines: Number of lines before/after each match to include. When 0 (default), returns only matching file paths. When > 0, returns matches with surrounding context.

Returns: Newline-separated list of matching note paths, or formatted results with context for each match

Capture content into a configured capture location.

Args: name: Name of the capture (e.g., 'inbox', 'log'). text: Main content to capture (passed as 'text' variable). extra_vars: Optional dictionary of additional variables.

Returns: Result of the capture command.

Update frontmatter metadata in a note, preserving existing fields.

Args: note_path: Path to the note relative to vault root metadata_json: JSON string with metadata fields to update/add

Returns: Success message or error description

Append content to a note, optionally within a specific subsection.

Args: note_path: Path to the note relative to vault root content: Content to append subsection: Optional heading title to append under. If not found, creates it at end.

Returns: Success message or error description

Replace text in a note's body content.

Performs plain string find-and-replace on the note body (not frontmatter). Fails if old_text is not found.

Args: note_path: Path to the note relative to vault root. old_text: The exact text to find. new_text: The replacement text. count: Number of occurrences to replace. 1 = first match only (default), 0 = replace all.

Returns: Success message or error description.

Update the status of a task checkbox in a note.

Args: note_path: Path to the note relative to vault root task_pattern: Text pattern to identify the task (matches task content) completed: True to mark as completed [x], False to mark as incomplete [ ]

Returns: Success message or error description

Find all notes that link to the specified note.

Args: note_path: Path to the note relative to vault root

Returns: Newline-separated list of notes linking to this note, or message if none

Find all notes that the specified note links to.

Args: note_path: Path to the note relative to vault root

Returns: Newline-separated list of linked notes, or message if none

Create a new zettel (atomic knowledge note).

Zettels are stored in the Zettel/ directory (or as configured by the vault's type definition). Each zettel captures a single atomic insight.

Args: title: Title of the zettel (the atomic insight). short_title: Short slug for the filename (e.g. "attention-mechanism"). source: Optional source reference as a wikilink (e.g. "[[literature-note]]"). body: Optional body text elaborating on the insight. connections: Optional list of related note wikilinks (e.g. ["[[note-1]]", "[[note-2]]"]). extra_vars: Optional dictionary of additional template variables.

Returns: Result of the creation including the file path.

Create today's daily note from the configured template.

Uses the vault's daily template to create a fully structured note with all standard frontmatter fields and sections. If the note already exists, returns a message without overwriting.

Args: date: Optional date in YYYY-MM-DD format. Defaults to today. extra_vars: Optional dictionary of additional template variables.

Returns: Result of the creation or message if note already exists.

Append content to today's daily note under an optional subsection.

Creates the daily note and its parent directories if they don't exist. The note path matches the configured 'daily_format' (default: 'Journal/YYYY/Daily/YYYY-MM-DD.md').

For timestamped log entries, use log_to_daily_note instead.

Args: content: Content to append subsection: Optional heading title to append under.

Returns: Success message or error description

Quickly capture a thought, idea, or todo to today's daily note inbox.

Zero friction — just dumps content as a bullet point to the Inbox section. Creates the daily note if it doesn't exist.

Args: content: The thought, idea, or todo to capture.

Returns: Success message or error description.

Create a weekly note from the configured template.

Uses the vault's weekly template to create a structured note. If the note already exists, returns a message without overwriting.

Args: week: Week identifier in YYYY-WXX format, or a date expression like 'today', 'today + 1w'. Defaults to current week. extra_vars: Optional dictionary of additional template variables.

Returns: Result of the creation or message if note already exists.

Create a monthly report note from the configured template.

Creates a structured monthly report in Journal/YYYY/Monthly/YYYY-MM.md. If the note already exists, returns a message without overwriting.

Args: period: Reporting period in YYYY-MM format. Defaults to current month. period_start: Optional custom start date (YYYY-MM-DD) for non-calendar periods. period_end: Optional custom end date (YYYY-MM-DD) for non-calendar periods. extra_vars: Optional dictionary of additional template variables.

Returns: Result of the creation or message if note already exists.

Append a log entry to the 'Logs' section of today's daily note.

Format: - HH:MM: Content

Args: log_message: The log message to append.

Returns: Success message or error description.

Run a predefined macro using the mdv CLI.

Args: name: The name of the macro to run (e.g., 'daily-standup', 'new-project') args: Optional list of positional arguments to pass to the macro variables: Optional dictionary of variables to pass to the macro (--var k=v)

Returns: Output of the macro execution or error message.

Get activity context for a specific day including tasks, notes modified, and logs.

Args: date: Date in YYYY-MM-DD format, or 'today', 'yesterday', or date expression.

Get task-centric activity context for a specific week.

Returns individual task lists (in-progress, completed, created), per-day focus breakdown, and project log entries. Use this to understand what happened at the task level during a week.

For aggregate metrics (heatmap, coverage, top completed counts), use get_activity_report with a week parameter instead.

Args: week: Week identifier ('current', 'last', YYYY-Wxx), or None for current.

Get context for a specific note including metadata, sections, activity, and references.

Args: note_path: Path to the note relative to vault root. activity_days: Number of days of activity history to include.

Get context for the currently focused project.

Returns the active project with task counts, recent tasks, and activity. Use this to understand what the user is currently working on.

Set the active project focus.

Args: project: The project ID or name to focus on. note: Optional note about what you are working on.

Clear the active project focus.

List all projects with task counts.

Args: status_filter: Filter projects by status (e.g., 'active', 'archived'). kind_filter: Filter by kind ('project' or 'area').

Get rich context for a project: metadata, sections, tasks, activity, and references.

Returns the full context note output for the project, including recent task activity, backlinks, and outgoing links.

Args: project_name: Name or ID of the project.

Show detailed status of a project (Kanban view).

Args: project_name: Name or ID of the project.

Show progress metrics for a project or all projects.

Args: project_name: Optional project name to get detailed progress for. If omitted, shows summary for all projects.

Create a new project or area.

Args: title: Title of the new project or area. context: Project context (e.g. 'work', 'personal'). description: Optional description of the project (max 1024 chars). status: Project status (e.g. 'open', 'in-progress', 'blocked', 'done', 'archived'). kind: Either 'project' (finite goal, default) or 'area' (ongoing responsibility). extra_vars: Optional dictionary of additional variables for the template.

Create a new meeting note.

Meeting notes have auto-generated IDs (MTG-YYYY-MM-DD-NNN) and are stored in the Meetings/ folder. Creation is logged to the daily note.

Args: title: Title of the meeting (e.g. "Team Sync", "Design Review"). attendees: Who's attending (e.g. "Alice, Bob, Charlie"). date: Meeting date in YYYY-MM-DD format. Defaults to today. extra_vars: Optional dictionary of additional variables for the template.

Returns: Result of the meeting creation including the generated meeting ID.

Create a new literature note from the template.

Literature notes are stored in Zettel/Literature/ and track reading progress through multi-pass reading (skimming, reading, completed).

Args: title: Full title of the paper/book/article. short_title: Short title for the filename slug (e.g. "attention-is-all-you-need"). authors: Author names, comma-separated (e.g. "Vaswani, Shazeer, Parmar"). year: Year of publication. url: URL or DOI link to the source. source_type: Type of source (article, book, video, podcast, other). extra_vars: Optional dictionary of additional template variables.

Returns: Result of the creation.

Archive a completed project.

Moves project and tasks to Projects/_archive/, cancels open tasks, clears focus if set, and logs the event. Only projects with status 'done' can be archived. Areas (kind: area) cannot be archived — they are ongoing.

Args: project_name: The project ID or folder name to archive.

Get area health report: criteria vs actuals for a period.

Checks the area's health_criteria against daily note metadata and returns how each standard is tracking.

Args: area: Area name or ID (e.g. 'health', 'HEA'). period: 'week', 'month', or specific like '2026-W11', '2026-03'.

Returns: JSON with area name, period, and criteria results (label, field, actual, target, met).

Export area metrics as CSV or JSON for trend analysis.

Dumps daily note metadata for the area's criteria fields over a date range. Useful for plotting trends externally.

Args: area: Area name or ID (e.g. 'health', 'HEA'). format: Output format ('csv' or 'json'). from_date: Start date in YYYY-MM-DD format. Defaults to 30 days ago. to_date: End date in YYYY-MM-DD format. Defaults to today.

Returns: CSV or JSON string with daily values for each criterion field.

Append a log entry to the 'Logs' section of any note (project, task, etc.).

Format: - [[YYYY-MM-DD]] - HH:MM: Content

Args: note_path: Path to the note relative to vault root. content: The log message to append.

Returns: Success message or error description.

List tasks with optional filters.

Args: project_filter: Filter tasks by project name. status_filter: Filter tasks by status ('todo', 'in-progress', 'blocked', 'done', 'cancelled', 'archived').

Show details for a specific task.

Args: task_id: The ID of the task.

Create a new task.

If no project is specified, mdvault automatically uses the active focus context. Context inheritance from the project is handled automatically.

Args: title: Title of the task. description: Optional description of the task (max 1024 chars). project: Optional project name. If omitted, uses the active focus context. due_date: Optional due date (YYYY-MM-DD). priority: Optional priority (e.g. 'low', 'medium', 'high'). status: Optional status (e.g. 'todo', 'doing', 'done'). extra_vars: Optional dictionary of additional variables for the template.

Mark a task as done.

Sets status to 'done' with a completion timestamp. Logs completion to the parent project note automatically.

Args: task_id: Task ID (e.g. "MDV-001") or path to the task file relative to vault root. summary: Optional summary of what was done (appended to task body).

Cancel a task.

Sets status to 'cancelled' with a timestamp. Logs cancellation to the parent project note automatically.

Args: task_id: Task ID (e.g. "MDV-001") or path to the task file relative to vault root. reason: Optional reason for cancellation (appended to task body).

Get the daily dashboard summary (today's tasks, events, etc).

Returns: The output of 'mdv today', summarizing the day.

Generate a metrics-centric activity report for a time period.

Returns aggregate productivity metrics: activity heatmap, daily note coverage, project progress stats, and actionable sections (overdue tasks, upcoming deadlines, high priority, stale notes). Supports both weekly and monthly periods (context week does not support monthly).

For task-level detail (individual task lists, in-progress tracking, per-day focus), use get_context_week instead.

Args: month: Month in YYYY-MM format (e.g. '2025-01' for January 2025). Cannot be used with 'week'. week: Week in YYYY-Wxx format (e.g. '2025-W05' for week 5 of 2025). Cannot be used with 'month'.

Returns: Activity report for the specified period.

Get a structured dashboard report with project metrics, velocity, and activity.

Returns a JSON report containing vault summary (notes/tasks by type and status), per-project breakdowns (task counts, progress %, velocity, recent completions), daily activity data, and actionable task lists (overdue, high_priority, upcoming_deadlines). Use for rich status checks, project reviews, and weekly/monthly reporting.

Args: project: Scope to a specific project (ID or folder name). Omit for vault-wide report. activity_days: Days of activity history to include (default: 30).

Returns: JSON dashboard report or error message.

Generate a visual PNG dashboard with charts and save it to the vault.

Produces a multi-panel PNG image with task status pie chart, project progress bars, activity timeline, and velocity comparison. The image is saved to assets/dashboards/ in the vault and can be embedded in notes via standard markdown image syntax.

Args: project: Scope to a specific project (ID or folder name). Omit for vault-wide dashboard.

Returns: Success message with path to the generated PNG, or error message.

Check vault structural correctness (broken links, schema violations, orphans, etc.).

Runs mdv check and returns an AI-friendly summary of vault health.

Args: category: Optional category to check (broken_references, malformed_wikilinks, schema_violations, structural_consistency, orphaned_notes, db_sync). Omit to run all checks. fix: If True, attempt to auto-fix fixable issues (not yet implemented).

Returns: Vault health report with issues grouped by category.

Validate notes against Lua type definitions (frontmatter schema).

Runs mdv validate to check that note frontmatter conforms to the type definition schemas (required fields, types, enums, defaults).

Args: path: Specific note path to validate (relative to vault root). Omit to validate all notes. note_type: Only validate notes of this type (daily, task, project, etc.). fix: Auto-fix safe issues (missing defaults, enum case normalisation). limit: Maximum number of notes to validate.

Returns: Validation report with per-note errors and fixes applied.