# Obsidian Starter Kit plugin for Obsidian The official companion plugin for the [[Obsidian Starter Kit]]. Adds strong typing support and powerful automation to [[Obsidian]] notes. It's what turns a vault into a solid knowledge management system with predictable structure, AI-friendly metadata, and minimal manual filing. Ships with OSK v4 and above. ## Features - **Note type system** — define custom note types with specific properties, tags, icons, folders, and templates - **Automatic recognition** — identify note types by tag, folder, or regex pattern (priority: tag > folder > regex) - **Property management** — global and per-type frontmatter properties with validation, allowed values, and defaults - **Property type sync** — registers every defined property's type in Obsidian's property registry (`.obsidian/types.json`), so the native property editor and [[Obsidian Bases|Bases]] render the right control (date picker, number, checkbox, list); only plugin-defined properties are touched, and disabling the sync removes exactly what the plugin added - **Select widget** — properties with allowed values get a dropdown (default value marked, invalid values highlighted in red) in the property editor and inside Bases table cells; values resolve per note type, so the same property name can offer different values on different types - **Validation and structure commands** — validate the current note, a folder or the whole vault with the plugin's own validator (the fixes are buttons in the report); recognize a note's type; insert the sections its template has and the note lacks; rename it to the type's name pattern; open its type in the settings; show its structure with the heading descriptions; check template drift. Each note type knows the sections of its template (descriptions included, kept in sync both ways) and `osk-cli sections <type>` exposes them. - **Conformance report** (since 1.55.0): lists the notes of a folder or of the whole vault that break their type, grouped by problem (missing or invalid properties, missing tags or name affixes, leftover template placeholders, empty list items, broken links, notes outside their folder), with bulk repairs you preview note by note before anything is written; `osk-cli conformance` and the MCP command `conformance_report` give the same report to scripts and AI assistants - **Bases integration** — invalid-value highlighting across Bases table rows (allowed values, number ranges, list items; global properties enforced even on unrecognized notes), plus commands to generate a ready-made `.base` file per note type (filters from its recognition mappings, columns with display names) - **Tag automation** — automatically add mandatory tags to recognized notes - **Automation rules** — per note type, "when a note enters a status, enters a done state, or a property condition becomes true, do this": stamp lifecycle dates, set progress, add or remove tags, move the note (a folder note moves with its whole folder, links updated). A rule can wait _n_ days after a date the note carries. The per-type **Archive** section (folder, delay, archiving statuses, and since 1.54.0 an optional archive date property that receives the day of the move) generates those rules for you — the archive grace period — and `osk-cli path <type> --field archive` tells any script where a type archives to. Runs from any edit source (editor, Templater, scripts, other plugins, CLI, MCP), never on startup, one write per real transition. - **File organization** — auto-move notes to their associated folder when recognized - **Visual icons** — per-type icons in the file explorer, tabs, and tab title bar - **Dynamic naming** — prefixes and suffixes with expressions like `{{date}}`, `{{year}}`, `{{month}}`, `{{day}}`; a prefix or suffix can be marked **optional** (since 1.22.0): a note without it is still valid and nothing adds it unless you ask, which is how a type retires a suffix without breaking the notes that carry it; since 1.55.0, a rename that drops a required prefix or suffix gets it back, links updated (rename again within 10 seconds to keep your name, or turn the setting off) - **md-base export** — export type definitions as human-readable files for AI/LLM integration and external validation (cfr [[Typed Markdown Collections Specification]]) - **`osk-cli`** — cross-platform CLI (Linux x64, Linux ARM64, Windows x64, macOS) shipped with the plugin - **MCP server** — exposes note type operations on `127.0.0.1:27125` for AI agent integrations - **Plugin API** — programmatic CRUD on all settings via `plugin.api`, usable from `obsidian eval` ## Settings overview All settings live under **Settings → Obsidian Starter Kit**. Since 1.55.0 they're split into groups (Note types, Properties and tags, Automation, Integrations, General, Support) behind a navigation bar, the note type and global property lists have a filter box and a count, and the note type editor shows one tab per section: - **Note types**: none in a fresh install of the plugin; the [[Obsidian Starter Kit]] ships its note types pre-configured, mapped to its folder structure - **Properties and tags**: global properties (frontmatter fields for every note, such as `created`, `updated`, `notes`, `review_count`), global tags for every note, and folder-scoped global tags - **Automation**: auto-add properties, auto-add tags, run automation rules and auto-move files are off in a fresh install to avoid surprises (the kit ships with automation rules on); keep name prefixes and suffixes on rename is on by default - **Integrations**: Obsidian integration (the Templater file creation trigger check, property type sync, the Bases folder); the MCP server, on by default on `127.0.0.1:27125`, with no API key in a fresh install (requests then aren't authenticated; the kit ships the key `osk`, kept per device in Obsidian's secret storage, not in `data.json`); Knowii Voice AI - **General**: the interface language (Obsidian's, English or French); note type icons in the file explorer, tabs and tab title bar; the types folder where md-base type files are exported (`_types` by default, `.types` in the kit); the vault folders (AI assistant, archives); Hide What's new - **Support**: links ## What happens when you modify a note type When you edit or add a note type in **Settings → Obsidian Starter Kit**: 1. The plugin updates its internal registry (`data.json`) 2. If auto-export is on, the matching `.types/<type-name>.md` md-base file is regenerated 3. Existing notes tagged with the type are NOT retroactively updated — they keep their current frontmatter until you run a sync command or manually re-apply 4. New notes created from the templates now follow the updated schema 5. The CLI validator (`osk-cli`) immediately reflects the new schema once `.types/` is regenerated **Property changes** (add, rename, remove) are non-destructive — existing notes keep their data; the plugin just updates the expected schema going forward. Use validation (via `osk-cli` or the UI) to find notes that drift from the new schema. **Tag/folder mapping changes** can immediately change which existing notes are "recognized" as a given type. Be careful when renaming tags — mass retag your existing notes first if needed. **Deleting a note type** removes it from the registry but does NOT delete the notes that used it. ## When to use it - You want **consistent metadata** across hundreds or thousands of notes - You want **AI agents** to reliably understand your vault structure (via md-base files and the MCP server); cfr [[Typed Markdown Collections Specification]] (md-base) - You want **auto-filing** so new notes land in the right folder without manual drag-and-drop - You want to **validate** notes from CI or a script (`osk-cli validate`) ## When not to use it - You prefer a fully manual, flat vault with no enforcement - You don't want any folder conventions (the plugin shines when paired with the OSK folder structure, but it's optional — all mappings are configurable) ## Full documentation The complete reference for this plugin lives inside the OSK user guide: [[Obsidian Starter Kit - Reference - OSK Plugin]]. It covers all settings, property and tag systems, the CLI validator, the MCP server, and tips & best practices. ## Related - [[Obsidian Starter Kit]] — the full kit this plugin powers - [[Obsidian Starter Kit - Reference - OSK Plugin]] — full plugin documentation - [[Obsidian Starter Kit - Tutorial - Configuring the Obsidian Starter Kit plugin]] - [[Obsidian Starter Kit - Reference - Note Types]] - [[Obsidian Starter Kit - Reference - Note Properties]] - [[Typed Markdown Collections Specification]] (md-base) - [[TypedMark]] (open spec generalizing this plugin's note-type system)