Discovery-First Workflow

The easiest way to create avoidable failures with md2wechat is to start making choices before you have confirmed the current runtime.

The steadier order is simple:

discover first, decide second, execute last.

Step 1: confirm the runtime surface

Start with:

md2wechat doctor --json
md2wechat capabilities --json

This answers:

• whether the local setup can attempt API-dependent work
• what the default mode is
• which high-level actions are exposed
• whether this runtime is ready for the workflow you have in mind

Step 2: list the available resources

Then check the resources that matter for your task:

md2wechat providers list --json
md2wechat themes list --json
md2wechat prompts list --json
md2wechat layout list --json

The point is straightforward:

• do not guess the provider
• do not guess the theme
• do not guess the prompt set
• do not guess the module catalog

Step 3: inspect the exact thing you plan to use

Once you know the direction, inspect the specific item:

md2wechat providers show volcengine --json
md2wechat layout show hero --json
md2wechat prompts show cover-hero --kind image --json

Now you can confirm fields, models, examples, and limits.

For layout modules, check body_format in the returned JSON. It tells you whether the module expects fields, rows, json_object, or json_array.

Step 4: execute the real task last

Only after that should you move to:

• convert
• preview
• generate_image
• article-draft

This order cuts down a large share of useless failures.

For article work, inspect the actual file before final execution:

md2wechat inspect article.md --json

If you are creating a draft, inspect the draft target with the same cover inputs you plan to use:

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

Why this matters more for agents

Humans can guess wrong once and recover.

Agents tend to build a full chain on top of the wrong assumption:

• the wrong theme
• the wrong module
• a model that does not exist
• AI mode treated like final output

A minimal starting workflow

For a first integration, use:

md2wechat doctor --json
md2wechat capabilities --json
md2wechat layout list --json
md2wechat layout show hero --json
md2wechat inspect article.md --json
md2wechat preview article.md

When to enforce this habit

Discovery-first is especially worth enforcing when:

• you are in a new runtime
• you just changed providers
• you just upgraded versions
• you are writing reusable rules for an agent

Continue with

• Mode Selection
• Doctor and Inspect Readiness
• Advanced Layout Mistakes
• Setup and Troubleshooting