add a bilingual authoring cookbook

[smf-h]

Problem and value

The repository has a strong Skill contract, but a first-time user still has to assemble the install, type-selection, validation, delivery, Architecture Delta, and visual-review steps from several files.

This PR adds a focused English/Chinese authoring cookbook and links it from all three README language surfaces.

Scope

• Added docs/authoring-cookbook.md.
• Added the matching Chinese guide at docs/authoring-cookbook.zh-CN.md.
• Added README links in README.md, README_EN.md, and README_ZH.md.
• No renderer, schema, CLI, generated artifact, or archify.zip changes.

Non-goals

• No new CLI behavior.
• No change to the existing Skill contract.
• No regeneration of Gallery pages or packaged files.

Tests run

• node bin/archify.mjs doctor — passed.
• node bin/archify.mjs guide "Show an API request with a Redis cache miss" --json — passed.
• Chinese guide recommendation with --lang zh — passed.
• node bin/archify.mjs validate sequence examples/cache-miss-request.sequence.json --quality showcase --json — passed: 9/9 checks, 0 errors, 0 warnings.
• npm test — the repository suite reached two environment-specific failures on Windows: preview termination expects a clean SIGTERM exit, and the Cursor archive test requires the Unix unzip executable. The documentation-related checks passed.

Generated artifacts

None. This PR changes documentation only; archify.zip remains fresh.

Visual evidence

Not applicable.

Review follow-up

Addressed all requested items:

• Consolidated the README reference links so the English README is exactly 2,070 words while README.md and README_EN.md remain byte-identical.
• Replaced the sequence delivery path with the known-contained examples/web-app.architecture.json Architecture example in both languages.
• The documented deliver and visual-check commands now complete successfully.
• Removed the trailing blank line from both new Markdown files.

Fresh verification:

• node --test test/readme-showcase.test.mjs — passed: 4/4.
• npm run check:release-identity — passed.
• node bin/archify.mjs deliver architecture examples/web-app.architecture.json web-app.html --quality showcase --json — passed: 9/9 checks, 0 errors, 0 warnings.
• node bin/archify.mjs visual-check web-app.html --json — passed containment and captures at 1440x900, 1600x1000, 1920x1080, and 2048x1320. The receipt correctly remains visualReview: pending for human review.

[tt-a1i]

Thanks for adding the bilingual authoring cookbook. The structure is useful, and I reproduced the doctor, English/Chinese guide, validate, inspect, deliver, and compare commands successfully.

I found two items that should be fixed before merge:

1. Against the current main, the full suite finishes at 628/629. test/readme-showcase.test.mjs reports README.md is too verbose again (2075 words) against the 2070-word budget. Please rebase/update and trim or consolidate the new README entry so this gate passes.

2. The documented end-to-end example does not reach a successful final visual check. After delivering examples/cache-miss-request.sequence.json to cache-miss.html, the exact documented visual-check command fails containment in all four desktop viewports because of vertical overflow. By comparison, delivering examples/web-app.architecture.json and running visual-check passes all four viewports. Please use a known-contained example consistently for the delivery/visual-check path, or add a concrete repair step so the advertised shortest reliable path actually finishes successfully.

Small cleanup: both new Markdown files also have a blank line at EOF (git diff --check).

There are currently no GitHub check results on this head, so please include the refreshed test and visual-check receipts after updating both language versions.

[smf-h]

Addressed the maintainer review comments in the latest commit. The updated PR description contains the exact verification commands and results.

[tt-a1i]

Thanks for the thoughtful bilingual cookbook. The technical content is solid, and the documented path is reproducible.

I would like to discuss one product-positioning point before we merge it. Archify is primarily an Agent-facing Skill, so the normal user journey should be:

The user describes the diagram they want → the Agent discovers and invokes Archify → the Agent selects the type, authors the JSON, validates it, repairs bounded issues, and delivers the HTML.

In that default path, users should not need to learn the schema or manually run validate, inspect, or deliver. The cookbook is still valuable, but I see its main audience as Agent integrators, contributors, advanced users, and people troubleshooting a failed automated run.

Would you be open to making that positioning explicit near the top? For example, one short note could say that normal users can simply ask a Skill-capable Agent to generate the diagram, and that the manual workflow below is a reference for integration, contribution, and troubleshooting. We could also label the README link accordingly.

What do you think? If this matches your intent, I believe it only needs a small wording adjustment, not a larger rewrite or expansion.