# mdflow

> A Git-native control plane for repeatable local agent work: Markdown flows, behavioral evals, and proposal-first evolution. Free MIT CLI; external engines may charge.

Workflows execute only through the local CLI; the website serves read-only documentation and source facts.

## When to use mdflow

Use mdflow for repeatable jobs such as code review, release-note drafting, and issue triage: keep one reviewed Markdown flow per job in your project's flows/ directory, version it in Git, and reuse its declared inputs. After creating and reviewing a code-review flow and approving execution, invoke it with `md flows/code-review.md`; release-note and issue-triage flows follow the same local CLI pattern. These example filenames are user-authored jobs, not bundled commands.

Install the [official mdflow npm package](https://www.npmjs.com/package/mdflow) with `npm install -g mdflow` (Bun is required), then run `md --version` and `md doctor --json`. Install and authenticate your selected engine separately. Doctor is static/read-only. A real flow run, eval, proposal, and source-changing apply require separate consent. Dry-run/explain may resolve imports; context isolation is not a host sandbox.

## Public source-facts interface

Use `GET https://mdflow.dev/facts.json` with `Accept: application/json` to read the public static snapshot. No authentication, request body, or mutations. The site supports HEAD for metadata. The snapshot is refreshed when the site is built and published; hosting caches may serve an earlier snapshot. It describes published CLI source, not a project's files, installed engines, readiness, or execution results.

The [OpenAPI 3.1 description](https://mdflow.dev/openapi.json) defines only GET /facts.json, with interface version `1.0.0`. The payload's `contract.contractVersion` is `1`; `versionBase` is the separate source CLI version. The [RFC 9727 API catalog](https://mdflow.dev/.well-known/api-catalog) links the specification and [HTTP usage documentation](https://mdflow.dev/docs/).

Responses include `X-API-Version: 1` and `Link` relations for service-desc and service-doc. Additive fields are allowed within v1; tolerate unknown fields. Breaking representation changes require a new URL and a new major specification version, rather than silently changing existing fields.

Site-handled errors use RFC 9457 `application/problem+json` with type, title, status, detail, a resolution hint, and an optional instance identifying the request: 404 for missing JSON resources, 405 for unsupported methods (Allow: GET, HEAD), and 406 for an unacceptable representation. Vercel hosting receives ordinary public request metadata and can produce its own error responses before site handling; see [privacy](https://mdflow.dev/privacy/). Check HTTP status and Content-Type before parsing a response.

## Start here

- [Homepage in Markdown](https://mdflow.dev/index.md): When to use mdflow, installation, engines, commands, and security boundaries
- [Documentation](https://mdflow.dev/docs.md): Public read-only HTTP usage, local CLI usage, and Flow UX Protocol v1 guidance
- [Facts and operation contract](https://mdflow.dev/facts.json): Static source facts for version 4.9.0, contract version 1; read-only public snapshot
- [Pricing and costs](https://mdflow.dev/pricing.md): Free MIT license and external-engine costs

## Source references

- [Project README](https://mdflow.dev/README.md): Installation, flow syntax, engine setup, and workflow examples
- [Public CLI reference](https://mdflow.dev/docs/public-api.md): Command and flag contracts, configuration, Flow UX Protocol v1, and errors
- [Evolution specification](https://mdflow.dev/docs/evolve.md): Proposal-first changes, feedback, proof, consent, apply, and rollback
- [Workflow feature guide](https://mdflow.dev/GUIDE-NEW-FEATURES.md): Steps, structured output, context providers, registry, and output modes
- [Security policy](https://mdflow.dev/SECURITY.md): Execution boundaries and private vulnerability reporting
- [Contribution guide](https://mdflow.dev/CONTRIBUTING.md): How to contribute to the project
- [mdflow agent skill](https://mdflow.dev/skills/mdflow/SKILL.md): The repository’s installable instructions for creating and maintaining flows
- [Skill digest index](https://mdflow.dev/.well-known/agent-skills/index.json): SHA-256 and source URL for the exact published skill bytes
- [Full documentation](https://mdflow.dev/llms-full.txt): Combined source documentation with source URLs

## Articles and trust

- [mdflow Evolve — change with proof](https://mdflow.dev/evolve-deep-dive.md): How feedback becomes a private prompt proposal with content-bound verification, capability checks, explicit review, atomic apply, and rollback.
- [About mdflow](https://mdflow.dev/about.md): A Git-native, open-source CLI for repeatable agent work, with inspectable inputs, behavioral evals, and proposal-first evolution.
- [Contact and security — mdflow](https://mdflow.dev/contact.md): Report mdflow bugs through GitHub issues and security vulnerabilities privately through GitHub Security Advisories.
- [Privacy — mdflow](https://mdflow.dev/privacy.md): How the static documentation site differs from local CLI execution, browser storage, hosting requests, and external engine processing.
- [GitHub repository](https://github.com/johnlindquist/mdflow): Source, releases, and contributions
- [Issue tracker](https://github.com/johnlindquist/mdflow/issues): Public bugs and questions
- [Private vulnerability reporting](https://github.com/johnlindquist/mdflow/security/advisories/new): Security reports; do not post exploit details publicly