docs: clarify AI mode list rendering behavior on WeChat mobile (issue #9)

.claude-plugin/marketplace.json

@@ -1,21 +1,21 @@
 {
   "name": "md2wechat-tools",
   "owner": {
-    "name": "geekjourney",
-    "email": "skrphper@gmail.com"
+    "name": "geekjourneyx",
+    "email": "zlisreallyli@outlook.com"
   },
   "plugins": [
     {
       "name": "md2wechat",
-      "source": ".",
-      "description": "Convert Markdown articles to WeChat Official Account formatted HTML with styled CSS. Supports API mode for quick conversion and AI mode for beautiful themed layouts (autumn-warm, spring-fresh, ocean-calm). Optionally upload to draft box.",
-      "version": "1.9.0",
+      "source": "./",
+      "description": "Convert Markdown articles to WeChat Official Account HTML, inspect resolved metadata and publish readiness, generate local preview artifacts, and optionally upload drafts.",
+      "version": "2.1.0",
       "author": {
-        "name": "geekjourney"
+        "name": "geekjourneyx"
       },
       "homepage": "https://github.com/geekjourneyx/md2wechat-skill",
       "repository": "https://github.com/geekjourneyx/md2wechat-skill",
-      "license": "MIT",
+      "license": "Source Available (BUSL-1.1)",
       "keywords": ["wechat", "markdown", "blog", "publishing", "html", "converter", "official account", "公众号", "排版"],
       "strict": false
     }

.github/copilot-instructions.md

@@ -0,0 +1,173 @@
+# Copilot Instructions — md2wechat
+
+**md2wechat** is a Go CLI tool that converts Markdown to WeChat Official Account format, with Claude Code and OpenClaw Skill support.
+
+## Build, Test, Lint
+
+```bash
+# Build for current platform
+make build
+
+# Run all tests (use GOCACHE to avoid conflicts)
+GOCACHE=/tmp/md2wechat-go-build go test ./...
+
+# Run a single package test
+GOCACHE=/tmp/md2wechat-go-build go test ./cmd/md2wechat/...
+
+# Run a single test by name
+GOCACHE=/tmp/md2wechat-go-build go test ./cmd/md2wechat -run TestRunVersionOutputsJSONEnvelope
+
+# Full CI-equivalent gate (run this before any release or CI-sensitive work)
+make quality-gates
+
+# Individual checks
+gofmt -l .       # formatting check
+go vet ./...     # static analysis
+make lint        # golangci-lint (same as CI)
+make release-check  # version/doc consistency
+```
+
+`make quality-gates` runs: format check → `go vet` → golangci-lint → `go test -count=1` → npm pack dry-run → `make release-check`. It is the authoritative local gate — identical to what GitHub Actions runs.
+
+## Architecture
+
+The main pipeline is:
+
+```
+cmd/md2wechat  →  inspect/preview (confirmation layer)  →  publish orchestrators  →  AssetPipeline  →  draft/wechat adapters
+```
+
+- **`cmd/md2wechat/`** — Cobra commands only. Handles arg parsing, calls internal packages, emits JSON envelopes and exits. No business logic.
+- **`internal/inspect`** — Single source of truth for resolved metadata, readiness, and publish checks. `preview` consumes inspect output; it does not re-implement business rules.
+- **`internal/preview`** — Read-only HTML confirmation page rendered from inspect state.
+- **`internal/publish`** — Main orchestration for article and image-post publish flows. Contains `AssetPipeline` (image upload/generate/download/rewrite) and `model.go` (canonical article/asset/artifact types).
+- **`internal/converter`** — Markdown → HTML, frontmatter extraction, image ref parsing, AI/API conversion.
+- **`internal/image`** — Image generation, compression, upload/download (injected at runtime).
+- **`internal/draft`** — WeChat draft adapter (standard article + `newspic` image post).
+- **`internal/wechat`** — WeChat SDK wrapper, material upload with retry, SSRF guard.
+- **`internal/promptcatalog`** — Loads prompt YAML assets from `internal/assets/builtin/prompts/`.
+- **`internal/config`** — Config loaded from file (`~/.md2wechat.yaml`) then environment variables.
+
+**Two skill paths share the same CLI binary:**
+- `skills/md2wechat/` — Claude Code / Codex / OpenCode agent skill
+- `platforms/openclaw/md2wechat/` — OpenClaw / ClawHub structured skill
+
+## Key Conventions
+
+### Discovery-first
+Before assuming any provider, theme, or prompt exists, query the running CLI:
+```bash
+md2wechat capabilities --json
+md2wechat providers list --json
+md2wechat themes list --json
+md2wechat prompts list --json
+md2wechat layout list --json      # advanced layout modules (43 built-in)
+```
+These are the source of truth. Do not guess from docs or stale memory.
+
+### Layout Module Discovery
+Advanced layout modules (43 built-in, 6 categories) are discovered and validated via:
+```bash
+md2wechat layout list --json                           # list all modules
+md2wechat layout list --serves attention --json        # filter by goal
+md2wechat layout show <name> --json                    # inspect a module
+md2wechat layout render <name> --var KEY=VALUE         # render syntax block
+md2wechat layout validate --file article.md --json     # validate syntax in file
+```
+
+**重要约束**：高级排版模块（`:::block` 语法）仅在 **API 模式**下渲染。
+- `convert`（默认）= API 模式，模块正常渲染
+- `convert --mode ai` = AI 模式，`:::block` 不渲染，以普通段落输出
+
+The 4 `serves` values that every module is mapped to: `attention` | `readability` | `memorability` | `conversion`.
+
+### E2E Rendering Smoke Test (required before every release)
+
+Before tagging or releasing, verify that advanced layout syntax renders correctly through the real API:
+
+```bash
+# Build latest CLI
+make build
+
+# Convert a test file with core layout modules (--mode api hits localhost:3000)
+./md2wechat convert examples/layout-e2e-test.md --mode api --output /tmp/layout-smoke.html
+
+# Check no raw ::: syntax remains in the output HTML
+python3 -c "
+modules = ['hero','toc','verdict','audience-fit','myth-fact','metrics','compare','steps',
+           'timeline','quote','callout','definition','author-card','subscribe',
+           'faq','checklist','cta','notice','summary']
+html = open('/tmp/layout-smoke.html').read()
+failed = [m for m in modules if ':::' + m in html]
+ok = [m for m in modules if ':::' + m not in html]
+print(f'PASS {len(ok)}/{len(modules)}') if not failed else print('FAIL - not rendered:', failed)
+"
+
+# Validate syntax is correct before running convert
+./md2wechat layout validate --file examples/layout-e2e-test.md --json
+```
+
+**Pass criteria:** Both checks pass (0 raw residuals, 0 validation errors). Do not tag or push a release until both are green.
+
+The canonical test file is `examples/layout-e2e-test.md`. Update it when adding new modules.
+
+
+
+### JSON Envelope Contract
+Every command emits a stable JSON envelope (schema version `v1`):
+```json
+{
+  "success": true,
+  "code": "CODE_CONSTANT",
+  "message": "human text",
+  "schema_version": "v1",
+  "status": "completed|action_required|failed",
+  "retryable": false,
+  "data": {},
+  "error": ""
+}
+```
+All `code` constants are declared in `cmd/md2wechat/main.go`. Adding a new command requires a new constant and a contract test in `main_contract_test.go`.
+
+### Configuration Naming Layers
+Three layers exist and must never be mixed in docs or guidance:
+- **Config file YAML keys** — e.g., `api.image_base_url`
+- **Environment variables** — e.g., `IMAGE_API_BASE`
+- **`config show --format json` output keys** — e.g., `image_api_base`
+
+### Prompt Catalog (YAML, not Go code)
+Image/humanizer/refine prompts live in `internal/assets/builtin/prompts/`. Do not embed long prompts directly in Go code. Humanizer supports 4 intensity levels: `gentle` / `medium` / `aggressive` / `authentic` — the `authentic` mode uses a standalone YAML prompt (`authentic.yaml`) that bypasses the base template. Every new `image` prompt YAML must include: `name`, `kind`, `description`, `version`, `archetype`, `primary_use_case`, `recommended_aspect_ratios`, `default_aspect_ratio`, `metadata.author`, `metadata.provenance`, `template`. The `default_aspect_ratio` must appear in `recommended_aspect_ratios`.
+
+### Test Discipline
+Tests protect contracts, not coverage numbers. Before writing any test, ask:
+1. Which failure would most damage user trust?
+2. Which failure would most mislead an agent?
+3. Which boundary must stay aligned between `inspect`, `preview`, `convert`, and `draft`?
+
+Priority: CLI contract tests → confirmation-vs-execution consistency → blocking readiness matrix → publish-path core → minimal real smoke. Use table-driven tests when behavior depends on input combinations. Do not add tests just to raise coverage.
+
+### Version Consistency
+All of these must stay aligned on release:
+- `VERSION` file
+- `.claude-plugin/marketplace.json`
+- `platforms/openclaw/md2wechat/SKILL.md` (install URLs)
+- `CHANGELOG.md`
+
+Quick check: `echo "VERSION: $(cat VERSION)" && grep '"version"' .claude-plugin/marketplace.json | head -1`
+
+### Documentation Sync
+Any change to CLI commands, flags, JSON output shape, providers, themes, or prompts must also update:
+- `README.md`
+- `docs/DISCOVERY.md`
+- `docs/FAQ.md`
+- `skills/md2wechat/SKILL.md`
+- `platforms/openclaw/md2wechat/SKILL.md`
+- `docs/HUMANIZE.md` when humanizer behavior or intensity levels change
+
+If the change affects config, install, or setup: also update `docs/CONFIG.md`, `docs/QUICKSTART.md`, `docs/USAGE.md`.
+
+### Git and Release Rules
+- Never `git push`, `git tag`, or `gh release create` without explicit user confirmation.
+- Never rebase or amend history unless the user explicitly asks.
+- GitHub Release is created automatically by `release.yml` when a tag matching `v*.*.*` is pushed — `gh` CLI is not required.
+- After `npm publish`, trigger `npx cnpm sync @geekjourneyx/md2wechat` so npmmirror stays current.

.github/workflows/ci.yml

@@ -0,0 +1,11 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  quality-gates:
+    uses: ./.github/workflows/quality-gates.yml

.github/workflows/quality-gates.yml

@@ -0,0 +1,29 @@
+name: Quality Gates
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  quality-gates:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Run unified quality gates
+        run: bash scripts/quality-gates.sh