[Timothee Guerin (timotheeguerin)]

The models guide recommends is Record<T> over extends Record<T> as though they were interchangeable, obscuring their inheritance and decorator behavior.

Explain when to copy a model versus preserve an inheritance relationship, how model-level and property decorators are handled, and that both record forms enforce their indexer constraints. The is example now demonstrates adding a property while retaining the source model’s documentation.

Fixes #8541

[github-actions]

No changes needing a change description found.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[Copilot]

🟢 Approval recommended

The focused documentation changes match the reviewed compiler behavior and existing tests, with no unresolved issues.

No open issues 🎉

What changed in this PR

Clarifies model copying versus inheritance in the TypeSpec models guide, addressing the confusion raised in #8541 without changing compiler behavior.

Changes:

• Explains when to use is versus extends, including record indexer constraints.
• Documents how spread, inheritance, and copying handle properties and decorators.
• Updates the is example to show an added property and preserved model documentation.

File	Description
website/​src/​content/​docs/​docs/​language-basics/​models.md	Clarifies model composition semantics and updates the copying example.

_{Review effort: Balanced}