v1.2.0 - Plugin System

What's new in 1.2.0

Plugin System

Frameworks built on MarkdownAI can now register themselves as plugins using a *.plugin.md file. The plugin declares its identity, detection signals, directory layout, and conventions in a structured format that any tool can read without guessing.

New directives:

• @markdownai-detect - detects which loaded plugins match the current project. Pass as=info for full metadata, include="layout,conventions" to filter sections.
• @plugin-data name="<plugin>" - returns a named plugin's full descriptor directly, bypassing detection.

New MCP tool:

• available_directives - returns the complete directive catalog (name, block/inline, close-tag). Pass include_plugin_directives=false to exclude plugin-file-only directives. Eliminates AI hallucination about what syntax exists.

Plugin file format (*.plugin.md):

Four new structured blocks valid inside plugin files:

• @plugin-meta - name, version, description, author
• @plugin-detect - required_dirs, required_files, required_marker, version_signal
• @plugin-layout - directory structure descriptor
• @plugin-conventions - naming rules and usage guidance

Plugin files are validated on load - any file containing executable directives (@query, @http, @db, etc.) is rejected.

Search paths (first-match wins per plugin name):

1. <projectRoot>/.markdownai/plugins/
2. ~/.markdownai/plugins/
3. /usr/share/markdownai/plugins/

API additions

• @markdownai/parser: getAvailableDirectives() returns DirectiveInfo[]
• @markdownai/engine: loadPlugins(), loadPluginsSync(), getPlugin(), getPluginSync(), detectPlugin(), clearPluginCache()
• @markdownai/mcp: availableDirectives() tool function exported

Stats

996 tests passing across all packages.

---

Full changelog: v1.1.2...v1.2.0

v1.0.0 - MDD integration fixes initiative

First major release. Sets a stable API baseline after a substantial feature initiative driven by integrating MarkdownAI into the MDD framework. The single-jail path-security model is replaced by a three-jail split; eleven new directives ship; the AI-integration story gains a SessionStart hook that injects rendered context with zero file mutation.

Breaking changes

Source vs data root split

The single jailRoot is gone. Three independent jails replace it:

Jail	Used by	Default
source_root	@import, @include	"auto" (entry-document directory)
data_root	@list, @read, @tree, @count, @date file=, @read-frontmatter, @hash, file.* helpers, @copy from=, @test/@check working dir	"cwd" (process working dir)
write_root	@mkdir, @copy to=, @append-if-missing, @update-frontmatter, @render-template to=	"cwd"

Why: v0.x jailed every filesystem op to the document directory, which made skill-file workflows impossible. A skill installed at ~/.claude/commands/mdd.md couldn't read its sibling templates while still reaching into the user's project. v1.0 separates the two concerns.

Migration: if you relied on data ops jailing to the document directory, set filesystem.data_root = "auto" in your security config.

@test and @check return full runner output

Previously @test/@check truncated to a tail or a one-line summary. They now return the complete combined stdout+stderr. The old label_output variable is removed; label now holds the full text. label_summary is additive (empty string when the runner isn't recognized).

New directives

Directive	Purpose
@foreach var in <source> ... @end	Iterate a list source. Source can be a directive, frontmatter list field, label, or CSV literal.
@set name = ...	Bind a value to a name. RHS can be literal, directive output, or interpolated string.
@read-frontmatter path field	Read a single YAML field from a doc's frontmatter.
@hash path algo length exclude-line	Compute a content hash with optional line-exclude regex.
@test command label	Run the project test suite. Auto-detects from package.json scripts.test.
@check command label	Run typecheck / lint / build. Auto-detects from typecheck / check / lint / build scripts.
@mkdir path	Create a directory. Recursive by default.
@copy from to if-missing	Copy a file. if-missing makes it idempotent.
@append-if-missing path text	Idempotent line append.
@update-frontmatter path field value	Set a YAML frontmatter field. Supports field[append], field[N], nested field[N].sub addressing.
@render-template from to ... @end	Render a template with injected parameters and write the result. Idempotent by default; force overwrites.

All write directives respect a new filesystem.write_enabled gate (off by default).

New @if helpers

The @if sandbox gains three content-aware helpers:

• file.containsLine(path, regex) - multiline regex test against a file
• file.containsSection(path, heading) - ATX heading match
• file.frontmatterField(path, field) - inline YAML field read

SessionStart hook (AI integration)

mai init now installs a SessionStart hook alongside PreToolUse. If a project has CLAUDE-MarkdownAI.md at its root, the hook renders it via mai render on every session start (and on resume / clear / compact) and injects the rendered output as additionalContext in Claude Code. Your CLAUDE.md is never modified - the rendered text lives only in conversation context.

The pattern: keep CLAUDE.md as static project rules. Put live data (today's date, current branch, open features, last test result) into CLAUDE-MarkdownAI.md using flat MarkdownAI directives.

Ironclad PreToolUse hook

The PreToolUse hook now:

• Detects MarkdownAI documents behind YAML frontmatter (Claude Code slash-command files like mdd.md).
• Returns a redirect message containing the complete catalogue of all 9 MCP tools (list_phases, resolve_phase, next_phase, read_file, execute_directive, call_macro, get_constraints, get_env, invalidate_cache) with argument shapes, return shapes, and a five-step workflow.

CLI

New flags on mai render for testing skill files locally with the same context the MCP server would supply:

• --skill-args "<args>" - sets ARGUMENTS, parses argsList, populates arg0..arg3. Defaults data_root to cwd when set.
• --skill-dir <path> - sets CLAUDE_SKILL_DIR.
• --skill-effort <low|medium|high> - sets EFFORT.
• --skill-session-id <uuid> - sets CLAUDE_SESSION_ID.

Bug fixes worth surfacing

• @include and @import paths now expand ${VAR} placeholders (HOME, CLAUDE_SKILL_DIR, CLAUDE_SESSION_ID, process env). Unset variables expand to empty string (fail-closed).
• || in @if conditions is now correctly distinguished from | (pipe).
• Source directives (@list, @read, @tree, @query, @db, @http) with label= now capture full multi-line output instead of just the first line.
• MCP resolve_phase propagates cwd into the engine context so data ops jail against the project root, not against mai-serve's own working directory.

VS Code extension

Full v1.0 directive support: grammar entries, snippets, completions, diagnostics, and auto-indent rules for every new directive. The extension still ships separately via the Marketplace.

Test totals at release

• parser: 160
• engine: 658
• renderer: 45
• mcp: 52
• core: 126
• vscode: 84
• e2e: 89
• Total: 1214 tests

Install

npm install -g @markdownai/core
mai --version  # 1.0.0
mai init       # installs PreToolUse + SessionStart hooks

All six @markdownai/* packages publish at the same version. The full change log lives in changed.md.

v0.0.20

What's new since v0.0.8

Documentation site

• New docs site live at https://markdownai.dev with full user guide
• Added 'What is MarkdownAI' section covering MCP execution model, read-time rendering, and phases as lazy-loaded workflow chunks
• Addresses the template engine misconception directly

VS Code extension

• Auto-language detection: .md files with @MarkdownAI header activate automatically
• Auto-indentation and auto-close for block directives
• Directive completions, hover docs, syntax highlighting for all directives including @constraint[level], @EnD, @endif
• Published to VS Code Marketplace as markdownai.markdownai

Package improvements

• MIT license added to all packages
• Correct npm descriptions for all packages (was showing raw badge HTML)
• markdownai.dev badge links added to all package READMEs

CLI

• mai init formatting hints injected into global CLAUDE.md
• .mai extension removed - MarkdownAI files are always .md with @MarkdownAI header

Tests

• 754 passing tests across parser, engine, renderer, security, phases, conditions, and pipe
• E2E test suite with 49 CLI verification tests

Install

npm install -g @markdownai/core

v0.0.8

What's new in v0.0.8

Bug fixes

• Blank lines preserved by default - blank-line nodes in rendered output were silently dropped. Now preserved without any flag required.
• mai --version now reads from package.json - was hardcoded to 0.0.1 regardless of installed version.
• mai security shell test command added - the shell jail test subcommand was documented but never wired up in the CLI. Now functional, exits code 1 if blocked (scriptable).
• @date timezone tokens fixed - zzz, ZZ, Z, A, a, hh, h, x, X tokens were passing through as literal text instead of being substituted.

Documentation

• README, manual, and CLAUDE.md updated with YAML frontmatter placement rule for @markdownai header.
• MDD feature docs 05, 16, 24, and 29 synced with all fixes.
• connections.md rebuilt for all 78 feature docs (was stale at 74).

Packages

All packages aligned at 0.0.8:

• @markdownai/parser
• @markdownai/renderer
• @markdownai/engine
• @markdownai/mcp
• @markdownai/core (mai CLI)
• markdownai (meta)

v0.0.1 - Initial Release

MarkdownAI v0.0.1

First public release of the MarkdownAI toolchain - a superset of Markdown that makes documents live.

Packages

Package	Description
@markdownai/core	mai CLI - render, validate, and manage live documents
@markdownai/engine	Execution core - evaluate directives, enforce security, handle caching
@markdownai/parser	Pure AST parser - no side effects, no execution
@markdownai/renderer	11 output format modules
@markdownai/mcp	MCP server for Claude Code and AI tool integration

Getting Started

npm install -g @markdownai/core
mai render ./your-doc.md

What's Included

• Full directive language: @env, @query, @http, @db, @connect, @list, @read, @tree, @count, @date, @define, @call, @include, @import, @if, @phase
• Security enforcement with per-feature enable/disable (mai security shell enable)
• Filesystem confinement, shell jailing, HTTP domain allowlists
• Built-in pipe commands (grep, sort, head, tail, wc, uniq) with no shell dependency
• MCP server for Claude Code integration
• SQLite, PostgreSQL, MySQL, MSSQL, MongoDB adapters
• 11 output formats including AI-optimized context

See the full spec for complete documentation.