[leoafarias]

Summary

• Add description: to @AckModel and @AckField.
• When no annotation description is set, read a single-line @description tag from a /// or /** */ doc comment. Annotation text takes precedence over the tag.
• Untagged doc prose and // comments never become schema descriptions. Tags inside fenced code examples are ignored; only a bare fence marker closes a fence. Blank or duplicate tags fail generation with a source-located error, and so does a blank description: annotation.
• Class descriptions apply to the wire object and the model codec, including sealed union bases and branches, so XSchema.schema, wireSchema, toJsonSchema(), and toSchemaModel() agree. Field descriptions apply only at the property and don't change a nested model's own description.
• AckSchemaInference.applyDescription (shared inference) uses the same rule and honors @AckField(description:).
• Descriptions are emitted through fix(generator): escape control characters in generated string literals #164's shared dartStringLiteral, so annotation text such as 'First\nsecond' generates valid source.

Behavior change

This replaces the whole-doc-comment behavior that was on main but never released (1.6.2 did not export doc comments). Code that relied on untagged docs must add description: or an @description tag. The generator changelog and README, @AckModel/@AckField docs, typesafe-schemas.mdx, and llms.txt describe the rule.

The example models were updated and regenerated. The top commit also updates PUBLISHING.md to describe the full 1.7 beta scope.

Base: #164, which contains the inferred-literal fix this PR builds on. This branch was rebased after typed copyWith returned to 1.7. The runtime-build and graph test fixtures keep both the copyWith and the description cases. Review fix 2d632300 tightens fence closing, adds blank-annotation tests, makes the authored-description test able to fail, and renames tests that still described doc-comment export. A tag on an indented line (/// @description) is still read.

Closes #175

Validation

Validated locally on the combined 1.7 tree (feat/ackmodel-class-description, head 2d632300), which includes every PR in the stack:

• dart run melos run test --no-select passed. Strict analysis (--fatal-infos) found no issues in all seven packages. Tests passed: ack 1,311, ack_generator 347, ack_firebase_ai 98, ack_mcp_dart 63, ack_json_schema_builder 51, ack_annotations 8, plus the root and example suites.
• A clean regeneration (delete *.ack.dart/*.g.dart, then melos run build) reproduced the committed output exactly.
• dart scripts/api_check.dart 1.6.2 reported no breaking changes in any of the six packages. It cannot inspect generated consumer code, so it does not flag the typed copyWith getter; the ack_generator changelog documents that under Breaking.
• dart scripts/publish_dry_run.dart reported 0 warnings for all six packages. verify_release_tag v1.7.0-beta.1 --skip-ancestry, dart format --set-exit-if-changed, and git diff --check passed.
• No feat(ack): support Draft 2020-12 runtime import and export #171 or feat(generator): generate models from Draft 2020-12 schemas #167 commit is an ancestor of the stack.
• Each PR was reviewed by an Opus 5.5 agent (AI-slop review, adversarial change review, and a description check). The blocking findings (constrained Set codegen in chore(release): prepare Ack 1.7.0-beta.2 #168, schema import prefix in feat(generator): add a static schema shorthand to AckInfer models #174) and the non-blocking fixes are included.