obsidian-bases-generator

name	obsidian-bases-generator
status	beta
description	Use when the user wants a live, database-like dashboard over their Obsidian notes — a Base (.base file) that filters, groups, or tables notes by their properties or tags. Trigger phrases - "create a dashboard", "generate a base", "make a Bases view", "build a table view of my notes", "show all notes with status X", "surface my draft backlog", "notes missing a property". Also trigger when the user mentions ".base files", "Bases", "table view", "card view", or wants to filter or group notes by a frontmatter property or tag. This skill scans the vault for real property usage first and only proposes dashboards backed by properties that actually exist — it never invents properties that are not in the vault.

Obsidian Bases Generator

Generate live, database-like dashboards over the vault by writing .base files. Unlike a passive format reference, this skill is proactive: it inspects which properties are actually populated across the vault and only proposes dashboards that will contain real data. A dashboard built on a property that only three notes use is noise, not signal.

The core principle — scan first, propose second, write third. Never generate a Base against a property that does not meaningfully exist in the vault.

Principle — Core + Nahbereich + Report

Per docs/philosophy.md, every skill has three zones:

• Core: Scan the vault's real property usage, propose fitting dashboards, and write validated .base files.
• Nahbereich: This skill reads notes and writes one config file — it never edits, tags, or moves a note. So its adjacent-fix surface is narrow: when the scan hits notes with unparseable frontmatter (they cannot be indexed), report them, do not repair them. Frontmatter repair is the job of note-rename and property-enrich.
• Report: Every run produces a summary (Done / Findings / Unchanged) and, for anything the user should act on, a findings-file entry. See Report below.

Shared conventions

This skill obeys the plugin-wide conventions. Read them before writing:

1. ../../references/vault-autopilot-note.md — protected files and folders the scan must skip (_vault-autopilot.md, _vault-autopilot/, _trash/, and every _* / .* folder). Note: this file also documents the planned "Obsidian Base View" — this skill is the active realization of it.
2. ../../references/findings-file.md — the append-only findings ledger and its Class A–D severities.
3. ../../references/config-spec.md — folders.excluded_prefixes (default ["_", "."]) and scope (inbox / vault / folder:<path>).
4. references/bases-syntax.md — the Bases file-format: filters, formulas, views, quoting, the two Duration/null pitfalls, and the verified hasTag / inFolder / groupBy matching semantics. Read this before writing any .base file.

Step 1 — Vault discovery and property scan

Resolve the vault via ${OBSIDIAN_VAULT_PATH} (no hardcoded paths — docs/philosophy.md). Then run the bundled scanner, which excludes the protected folders, parses YAML frontmatter, and reports property coverage, the tag inventory, and the folder inventory:

python3 scripts/scan_properties.py "${OBSIDIAN_VAULT_PATH}" --json /tmp/vault-scan.json

Report the result to the user as a coverage table before proposing anything. Coverage — the percentage of notes carrying a property — is the deciding metric. Example shape (yours will differ; always use the live scan, never these numbers):

Property	Notes	Coverage	Top values
tags	1478	92%	(see tag inventory)
status	734	46%	draft, active, referenz, aktiv, final
type	638	40%	inbox, skill, prompt, reference
description	1104	69%	TBD, (empty), …

A property under ~20% coverage is a weak dashboard target — the scanner flags it, and so should you. Do not lead with a weak property, and never propose a dashboard for a property the scan did not find.

Step 2 — Propose dashboards (one question at a time)

Map real property patterns to dashboard archetypes. Three archetypes ship as starter templates in assets/:

1. Lifecycle (status, type) → a grouped table showing the backlog by state — assets/dashboard-inbox-drafts.base.
2. Gap (a property missing or set to a sentinel like TBD on many notes) → a "needs attention" table surfacing exactly those notes — assets/dashboard-property-gaps.base.
3. Category + tag (file.hasTag(...) grouped by a derived category) → a chronological index filtered by tag — assets/dashboard-research-reports.base.

Do not propose an archetype the vault does not support. If status has good coverage but there is no priority property anywhere, do not offer a priority board.

Present the proposal, then ask the single most useful narrowing question — for example whether the draft dashboard should cover only the inbox folder or the whole vault. Reassess after the answer. Keep it to one question at a time.

Step 3 — Generate the .base file

Read references/bases-syntax.md first, then adapt the closest starter template to the real property names and values from Step 1. Never ship a template unchanged if the vault's property names differ — the templates in assets/ were reconciled against one real vault and will not match another's status values, folder names, or category tags.

Three format rules are non-negotiable (full detail in the reference):

1. Null-guard every note-property formula. Note properties are absent on many notes. Wrap the whole formula: if(status, if(status == "draft", "✏️", …), ""). File metadata (file.ctime, file.mtime, file.name) is always present and needs no guard.
2. Duration needs field access before rounding. Date subtraction returns a Duration, not a number. Use (now() - file.ctime).days.round(0), never .round() on the raw Duration.
3. YAML quoting. Single-quote any formula that contains double quotes; quote strings containing : and other special characters.

A .base file is pure YAML config — it does NOT get Obsidian Markdown properties (title::, version:: etc.). Those belong to .md notes only.

Status icons and emoji. The starter templates use emoji glyphs in status_icon / gap-marker columns because a glyph column is the idiomatic Bases way to make state scannable at a glance. This is a deliberate exception to the plugin's no-emoji rule, which governs instructional and prose files, not a rendered dashboard column. If the user prefers text, the icons are a one-line change — offer that.

Filename and placement

1. Filename uses the vault separator em-dash –, e.g. Dashboard – Inbox Drafts.base. Max ~70 characters. (The template files in assets/ use ASCII hyphens in their repo filenames; the generated vault file uses the em-dash.)
2. Default placement: a dedicated 030_Systems/Dashboards/ folder, or the vault root. Ask the user once where dashboards should live and reuse the answer for the session.

Step 4 — Validate

Validate every generated base before writing is complete. A silently broken base renders as a YAML error, or a column that never appears, in Obsidian:

python3 scripts/validate_base.py <generated-file>.base

The script checks valid YAML and that every formula.X referenced in order, groupBy, summaries, or properties is defined under formulas. It does not check the Bases expression language itself — so also confirm by eye against references/bases-syntax.md:

1. Every note-property formula is null-guarded with if().
2. No raw .round() / .floor() / .ceil() on a Duration (field access first).
3. filters is a single string or an and / or / not object — never a bare YAML list.
4. Any view that groups by a formula.X is flagged to the user to confirm on first open (groupBy-on-formula is not officially documented).

If validation fails, fix before presenting. Never write a base you have not validated.

Step 5 — Confirm and write

Show the user a preview — the YAML plus a plain-language description of what each view will show — and confirm before writing. This single confirm gate is the only manual step in the run.

On write, follow the same overwrite logic the other skills use:

1. NEW — no file at the target path: write it.
2. EXISTS — a .base already exists at the path: show the diff and ask before overwriting; never silently replace a user-tuned base.
3. TRASHED — the target name exists in _trash/: treat as NEW at the live path, do not resurrect the trashed copy.

After writing, tell the user:

1. The base filename and folder.
2. How to open it — open the .base directly, or embed with ![[Dashboard – Name.base]].
3. That a single view embeds as ![[Dashboard – Name.base#View Name]].

Report

Mandatory after every run. Use the plugin's non-negotiable report shape (docs/philosophy.md):

## Bases Generator Report — [Date]

### Done
- Created [n] bases: [filenames]

### Findings
- [n] notes with unparseable frontmatter (→ note-rename / property-enrich)
- [n] weak-coverage properties flagged (below 20%)

### Unchanged
- [n] notes scanned, read-only — no note was edited

For anything the user should act on (unparseable frontmatter, a large metadata gap the scan surfaced), append a Class A–D entry to the findings ledger per ../../references/findings-file.md:

${OBSIDIAN_VAULT_PATH}/_vault-autopilot/findings/<YYYY-MM-DD>-obsidian-bases-generator.md

Then append one row to logs/run-history.md:

| <date> | obsidian-bases-generator | <scope> | <scanned> | <bases created> | <notes edited: always 0> | <findings> |

Quality Checklist

1. The scan ran against the live vault and the coverage table was shown before any proposal.
2. Every filter and formula references only properties or tags the scan actually found.
3. Every generated base passed scripts/validate_base.py.
4. Every note-property formula is null-guarded; no raw Duration rounding.
5. No .base carries Markdown frontmatter properties.
6. groupBy-on-formula views were flagged for first-open verification.
7. No note was edited — this skill reads notes and writes only .base config plus its own findings and run-history entries.
8. User confirmed before the file was written.

Changelog

• 2026-07-12: Initial version. Bases format reference distilled from kepano/obsidian-skills (MIT) into references/bases-syntax.md, extended with verified hasTag / inFolder / groupBy semantics. Automation layer added on top: bundled scripts/scan_properties.py (coverage + tag + folder scan with plugin-standard exclusions) and scripts/validate_base.py (YAML + formula-reference check across order / groupBy / summaries / properties). Three starter dashboards reconciled against a real vault. Grounded in the plugin's real conventions (references/vault-autopilot-note.md, findings-file.md, config-spec.md) rather than an assumed _conventions file; status icons kept as a deliberate, documented emoji exception.

Run History

Date	Scope	Notes scanned	Props found	Bases created	Learnings
2026-07-12	vault (build-time scan)	1610	130+ keys; 9 above 20% coverage	0 (templates reconciled, not written to vault)	Assumed status polished/archived do not exist (real: draft/active/aktiv/referenz/final); type: TBD sentinel does not exist (real type gap is missing type, ~60%); TBD sentinel lives on description; assumed Protocol category tag absent (real: Trading/Finance dominate, then OpenSource/Software); 11 notes have unparseable frontmatter plus quoted-key artifacts (created: / status: as keys) — Class-C, routed to note-rename/property-enrich.

First-run coverage table (2026-07-12, vault scan of 1610 notes, 1522 with frontmatter)

The dashboard-worthy properties (above the ~20% coverage floor), captured verbatim from scan_properties.py:

Property	Notes	Coverage	Top values
tags	1478	92%	(see tag inventory)
created	1304	81%	dates
title	1280	80%	free text
description	1104	69%	TBD (33), (empty) (26), …
modified	798	50%	dates
status	734	46%	draft (284), active (179), referenz (118), aktiv (91), final (11)
type	638	40%	inbox (178), skill (158), prompt (73), reference (51)
source	471	29%	apify/instagram-scraper (42), …
last_modified	418	26%	dates

Everything else scanned below 20% coverage (weak targets, not led with). Folder inventory: 020_Processes (462), 030_Systems (417), 010_Outcomes (339), 001_Inbox (332), 099_Archive (37). Research-tag sub-scan: 41 notes, category tags Trading (11) / Finance (9) / OpenSource (8, incl. nested OpenSource/AI-ML) / Software (4, incl. nested Software/DevTools, Software/Infrastructure); status draft (22) / abandoned (1).