Authoring guide: define the complete proposal workflow

[noeltock]

Problem

The shipped guide proves that a section with a heading and paragraph can compile, but it does not describe enough of AuthoringProposal to author a complete design. Fresh attempts have borrowed node label from the advanced full-plan contract, bound a figure to a layout wrapper, or selected Columns for a supplied CSS grid. Each choice reaches a different rejection before the requested editing experience can be evaluated.

The guide labels these as separate workflows, so this is not a claim that one schema contradicts itself. The missing piece is a complete, discoverable authoring contract. The smallest next step is to establish that contract without adding a translator or changing the compiler.

Approach

SKILL entry point
  → registered authoring: proposal keys + source binding + supported native mappings
  → runnable representative example through packed author()
  → canonical preview/confirmed write

Advanced complete plans and page-content assembly remain separate reading paths.

Keep the existing responsibility split: the caller chooses structure, source bindings, editability, locking and explicit design changes; core derives source facts, assets, coverage, native selector adaptation and required warning text. This issue changes instructions and deterministic tests, not runtime behaviour.

Existing code and evidence

Reviewed candidate: PR #69 at 9680c5cc66bf17a3f803cf2eff4ddd75d41bdbf5, based on main 410ac4dbf7cde97f1894f108cb3f95a09a60caa6. #62–#64 are delivered. #69 remains draft. Reconcile its existing changes before starting; do not rebuild its example, fixture or runtime worker from scratch.

• GUIDE.md: proposal example starts at line 68; advanced complete-plan shape at line 108; page-content structural guidance around line 434. The latter recommends Columns for layouts that authoring may need to retain as an authored grid.
• src/author/proposal.ts: normalizeAuthoringProposal, normalizeNode, bindAuthoringProposal, sourceAttributes and validateProposalSourceContent are the contract to document. Cross-check AuthoringProposal/AuthoringProposalNode in src/types.ts; do not copy the similarly named complete-plan shape.
• src/author/plan.ts: adaptNativeSourceStyles implements bounded native ownership. It refuses Columns owning an authored grid. Document supported choices rather than promising arbitrary CSS conversion.
• test/author.proposal.test.ts: the complete utility/hero-handoff.html test already preserves content and proves canonical round-trip, but declares only the heading editable. Extend this test; do not mistake the partial layout tests with explicit omission decisions for complete-design proof.
• scripts/smoke-packed-cli.mjs already executes the marked guide example through installed exports. Extend that existing check; no second example-extraction framework.

Required contract detail

Document exact root and node keys, required node IDs, source references scoped to the exact input, and the distinction between a source-bound node and a synthetic structural wrapper. Show supported figure → Image ownership, image/caption retention, Buttons → Button nesting and a Group retaining an authored grid. Explain that a wrapper without sourceRef does not consume the source element or excuse missing content. Derive references through collectSourceEvidence; never teach callers to manufacture offsets or hashes.

Explain which content attributes core supplies, including image dimensions, links, alt text and captions. Normal authoring should omit redundant copies; actual content changes require explicit source decisions. Keep the exact canonical full-plan and permissive page-content routes supported without mixing their keys into the proposal example.

Use a small representative design with image/caption, CTAs and supplied layout CSS for the public worked example. It must differ from the held-out hero used in #65; do not turn that evaluation's expected tree into shipped instructions.

Acceptance criteria

• SKILL.md routes registered authoring to a complete proposal reference without requiring callers to read the advanced plan or page-content contract first.
• Every documented proposal field agrees with the actual normaliser; full-plan-only fields such as node label are clearly scoped.
• The representative example runs through the existing installed-package smoke path and derives its source content/coverage/assets without hand-authored ledgers or adapters.
• The existing full hero test declares and verifies separate editable eyebrow, heading, body, both CTA texts, product image URL and image alt fields. Existing CTA URLs, caption and assets remain preserved. Retain content-only locking and assert canonical field bindings, not merely a field count.
• Full hero proof has no omission decisions, preserves source content and deterministic round-trip, and retains tamper rejection.
• Required field combinations compile through the existing native editable-field validation. If this reveals an unsupported compiler contract, report the exact blocker before expanding implementation scope.
• Compiler source, dependency versions, source fixture and evaluation thresholds are unchanged by this issue. The tests establish expert-authored feasibility, not model usability or WordPress editing proof.

Checks and sequence

Run npm test -- test/author.proposal.test.ts test/author.native-style-adapters.test.ts, npm run typecheck, then build and npm run smoke:package for the final instruction package. Refresh the existing authoring hash manifest only if its normal check requires it; never change benchmark inputs to make the hashes pass. Run required integration checks once the change is stable, not after each prose edit.

This is the prerequisite for the instruction-only experiment in #65. Complete that comparison before integrating runtime corrections into its compiler baseline. No paid model run, new semantic schema, automatic native-tree rewrite, raw HTML fallback or publication is part of this issue.