md2wechat 2.4.0: Readiness Targets, Doctor Checks, and Safer Agent Workflows

md2wechat-skill has passed 2.7k GitHub stars, and the official docs now need to reflect how the current tool actually works.

The most important change in md2wechat 2.4.0 is not a new command. It is a clearer decision surface for agents.

Agents can now inspect one article and decide whether preview, convert, upload, or draft is ready, blocked, degraded, or not requested.

What changed in 2.4.0

inspect --json now exposes a stronger readiness contract:

{
  "data": {
    "readiness": {
      "schema_version": "1",
      "targets": {
        "preview": "ready",
        "convert": "ready",
        "upload": "not_requested",
        "draft": "blocked"
      },
      "blockers": [
        {
          "code": "MISSING_COVER",
          "target": "draft"
        }
      ]
    }
  }
}

The key fields are:

• data.readiness.targets
• data.readiness.blockers
• data.readiness.schema_version

Older booleans such as convert_ready, upload_ready, draft_ready, and preview_fidelity still exist, but new agent workflows should prefer targets and blockers.

Why this matters for agents

Before this contract, an agent often had to infer too much:

• whether preview was safe
• whether conversion could run
• whether upload was requested
• whether draft creation was blocked by missing cover material
• whether the issue was local configuration or article-specific input

That kind of guessing creates fragile workflows.

With targets and blockers, the agent can make a smaller and safer decision:

The article can be previewed and converted, but draft creation is blocked because the cover is missing.

That is the kind of answer a user can act on immediately.

Doctor is for local setup

md2wechat 2.3.0 added:

md2wechat doctor --json

Use it before API-dependent work.

doctor checks local attemptability: config loading, default convert mode, API key presence, default theme compatibility, layout catalog availability, and WeChat draft credential presence.

It does not perform live authentication. It does not upload images. It does not create drafts.

The practical order is:

md2wechat version --json
md2wechat doctor --json
md2wechat capabilities --json
md2wechat inspect article.md --json
md2wechat preview article.md
md2wechat convert article.md

Inspect is for one article

inspect --json answers a different question:

can this article do the thing the user asked for?

For a draft workflow:

md2wechat inspect article.md --draft --cover cover.jpg --json

If draft creation is blocked, inspect can map the blocker to the target:

• MISSING_API_KEY
• LOCAL_IMAGE_MISSING
• MISSING_COVER

This is better than treating all failures as generic conversion failures.

Theme discovery also became stricter

md2wechat 2.3.1 and 2.3.0 tightened theme discovery.

Agents should now read themes list/show --json instead of guessing theme names from old docs.

Important fields include:

• selectable
• style
• metadata_incomplete

API mode rejects AI themes. AI mode rejects API themes. Non-selectable theme collections should not be used as concrete themes.

The safe pattern is:

md2wechat themes list --json
md2wechat themes show wechat-native --json
md2wechat convert article.md --theme wechat-native

Layout modules now expose body format

Advanced layout modules should be chosen from discovery output:

md2wechat layout list --json
md2wechat layout show hero --json

The important addition is body_format, which tells agents whether the module expects:

• fields
• rows
• json_object
• json_array

This removes the need to infer syntax from examples.

For generated Markdown, the safer path is:

md2wechat layout validate --file article.formatted.md --json

Then convert the validated temporary file.

Brand Profile is now part of the agent workflow

md2wechat 2.2.0 added:

md2wechat brand init
md2wechat brand show --json

Brand Profile lives at:

~/.config/md2wechat/brand.md

It is Markdown, not YAML. The CLI returns the raw text and the agent uses it for voice, layout preferences, calls to action, and forbidden phrases.

This matters because advanced publishing work is not only a conversion problem. It is also a consistency problem.

Image defaults changed after 2.2.1

md2wechat 2.2.1 fixed OpenAI GPT Image handling when image models return b64_json, and updated the default OpenAI image model to gpt-image-2 with auto size.

If image generation behaves differently after upgrade, check:

md2wechat providers list --json
md2wechat providers show openai --json
md2wechat config show --format json

Do not copy old image defaults into a new config without checking provider discovery first.

Recommended current workflow

For agent-safe publishing in current md2wechat, use this order:

1. Check local setup with doctor --json.
2. Discover only the provider, theme, prompt, or layout resource needed for the task.
3. Keep the user's source Markdown read-only.
4. Create a temporary formatted Markdown file when adding layout modules.
5. Validate layout syntax.
6. Inspect the article target readiness.
7. Preview before final conversion or draft creation.

The compact command sequence is:

md2wechat doctor --json
md2wechat themes list --json
md2wechat layout list --json
md2wechat layout validate --file article.formatted.md --json
md2wechat inspect article.formatted.md --json
md2wechat preview article.formatted.md
md2wechat convert article.formatted.md

What to read next

• Doctor and Inspect Readiness
• Brand Profile
• Discovery-First Workflow
• md2wechat-skill

Source: md2wechat-skill changelog