Fix metadata pages to show correct with { } placement

Metadata items (terms, options, author references, descriptions,
attachments) belong in `with { }` blocks after a definition's
closing brace, not inside the body. These pages incorrectly showed
them as body definitions.

- metadata.md: Complete rewrite with correct placement examples,
  fixed term syntax, option syntax, and author def vs ref split
- author.md: Clarify definitions (Module/Domain only) vs
  references (any definition's with { } block)
- term.md: Move all examples into with { } blocks, fix Occurs In
- option.md: Add `option is` syntax, fix Occurs In to metadata

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: respencer-ncl

docs/riddl/concepts/author.md

@@ -3,17 +3,67 @@ title: "Author"
 draft: false
 ---
 
-An author definition merely describes one of the authors that wrote the 
-encapsulating definition. An author definition contains the usual profile 
+An author definition describes one of the authors who wrote the
+enclosing model. An author definition contains the usual profile
 information for a human including:
+
 * full name
 * email address
 * name of an organization (optional)
 * title at that organization (optional)
 * url for more information (optional)
 
+## Syntax
+
+```riddl
+domain ECommerce is {
+  author Reid is {
+    name is "Reid Spencer"
+    email is "reid@ossum.com"
+  }
+
+  // ... domain body definitions ...
+}
+```
+
+## Author Definitions vs. Author References
+
+**Author definitions** can only appear in the body of a **Module**
+or a **Domain**. They are not permitted inside contexts, entities,
+or other processors.
+
+To associate an author with any other definition, use an **author
+reference** in that definition's `with { }` metadata block:
+
+```riddl
+domain ECommerce is {
+  author Reid is {
+    name is "Reid Spencer"
+    email is "reid@ossum.com"
+  }
+
+  context Catalog is {
+    ???
+  } with {
+    by author Reid
+  }
+}
+```
+
+The `by author` reference uses a path identifier that resolves to
+an author definition in an enclosing Module or Domain.
+
 ## Occurs In
-All [vital definitions](vital.md)
+
+Author **definitions** occur in:
+
+* [Root](root.md) (via Module)
+* [Domains](domain.md)
+
+Author **references** (`by author`) occur in:
+
+* [Metadata](metadata.md) blocks (`with { }`) on any definition
 
 ## Contains
-No other definitions
+
+No other definitions.

docs/riddl/concepts/metadata.md

@@ -3,32 +3,48 @@ title: "Metadata"
 draft: false
 ---
 
-Metadata in RIDDL provides supplementary information about definitions that
-doesn't affect the core semantics but aids documentation, organization, and
-tooling.
+Metadata in RIDDL provides supplementary information about
+definitions—documentation, terminology, attribution, and
+implementation hints—without affecting core semantics. All metadata
+lives in a `with { }` block that follows the definition's closing
+brace.
 
-## Common Metadata
+## Placement
 
-All definitions support these metadata elements:
+Metadata appears **after** a definition's body, not inside it:
 
-### Brief Description
+```riddl
+context OrderManagement is {
+  // body definitions go here (entities, types, handlers, etc.)
+  ???
+} with {
+  // metadata goes here
+  briefly "Manages the order lifecycle"
+  term Fulfillment is {
+    |The complete process of receiving, processing, and
+    |delivering an order to the customer.
+  }
+  option is technology("Kafka")
+}
+```
+
+## Brief Description
 
-A short, one-line description using `briefly`:
+A short, one-line summary using `briefly`:
 
 ```riddl
-entity Customer is {
+entity Customer is { ??? } with {
   briefly "A person or organization that purchases products"
-  // ...
 }
 ```
 
-### Extended Description
+## Extended Description
 
-Longer documentation using `described by` (or `described as`, `explained by`,
-`explained as`):
+Longer documentation using `described by` (or `described as`,
+`explained by`, `explained as`):
 
 ```riddl
-entity Customer is {
+entity Customer is { ??? } with {
   described by {
     |Customers are the primary actors in our e-commerce system.
     |They can browse products, place orders, and manage their
@@ -37,52 +53,116 @@ entity Customer is {
 }
 ```
 
-The `|` prefix indicates lines of documentation text (Markdown format).
+The `|` prefix indicates lines of documentation text in Markdown
+format.
 
-### Terms
+## Terms
 
-Domain-specific terminology with definitions:
+Domain-specific terminology defined as glossary entries. The syntax
+is `term` *identifier* `is` *doc_block*:
 
 ```riddl
 domain ECommerce is {
-  term "SKU" is described by "Stock Keeping Unit - unique product identifier"
-  term "Cart" is described by "Temporary collection of items before checkout"
+  context Catalog is {
+    ???
+  } with {
+    term Listing is {
+      |A product's presence in the catalog, including its
+      |description, images, pricing, and availability.
+    }
+  }
+} with {
+  term SKU is {
+    |Stock Keeping Unit—a unique identifier for a specific
+    |product variant, including size, color, and other
+    |attributes.
+  }
 }
 ```
 
-### Authors
+## Options
 
-Attribution for definitions:
+Options are instructions to translators about how a definition
+should be implemented or interpreted. The syntax is `option is`
+*option_name* with optional string arguments:
 
 ```riddl
-author Reid is {
-  name "Reid Spencer"
-  email "reid@example.com"
+entity Order is {
+  ???
+} with {
+  option is event-sourced
+  option is aggregate
+  option is technology("Akka")
+  option is kind("core")
 }
+```
+
+See [Options](option.md) for the full list of available options
+per definition type.
+
+## Author Definitions vs. Author References
+
+RIDDL distinguishes between **author definitions** and **author
+references**. They serve different purposes and appear in different
+places.
+
+### Author Definitions (Body)
+
+Author definitions declare who created or maintains a model. They
+can **only** appear in the body of a **Module** or **Domain**—not
+in contexts, entities, or other definitions:
+
+```riddl
+domain ECommerce is {
+  author Reid is {
+    name is "Reid Spencer"
+    email is "reid@ossum.com"
+  }
 
-domain MyDomain by author Reid is { ... }
+  context Catalog is { ??? }
+}
 ```
 
-## Options
+See [Author](author.md) for full details.
 
-Options modify the behavior of definitions. Common options include:
+### Author References (Metadata)
 
-- `technology("x")`: Implementation technology hints
-- `kind("x")`: Classification of the definition
-- `css("x")`: Styling hints for documentation
-- `faicon("x")`: Font Awesome icon for documentation
+Author references use `by author` to associate an existing author
+definition with any definition's metadata:
 
 ```riddl
-context OrderManagement is {
-  option technology("Akka")
-  option kind("core")
-  // ...
+domain ECommerce is {
+  author Reid is {
+    name is "Reid Spencer"
+    email is "reid@ossum.com"
+  }
+
+  context Catalog is {
+    ???
+  } with {
+    by author Reid
+  }
+}
+```
+
+## Attachments
+
+Attachments associate external files (diagrams, spreadsheets,
+images) with a definition:
+
+```riddl
+entity Order is {
+  ???
+} with {
+  attachment StateChart is "diagrams/order-states.png"
+    as "image/png"
 }
 ```
 
 ## Occurs In
 
-Metadata can appear in any definition, including:
+Metadata (`with { }` blocks) can appear on any definition,
+including:
 
 * [Domains](domain.md)
 * [Contexts](context.md)
@@ -92,8 +172,12 @@ Metadata can appear in any definition, including:
 
 ## Contains
 
-Metadata does not contain other definitions; it contains:
+Metadata blocks contain:
 
-* Literal strings (descriptions, term definitions)
-* Options with parameters
-* Author references
+* Brief descriptions (`briefly`)
+* Extended descriptions (`described by`)
+* [Terms](term.md) — glossary entries
+* [Options](option.md) — translator instructions
+* Author references (`by author`)
+* Attachments
+* Comments

docs/riddl/concepts/option.md

@@ -3,26 +3,43 @@ title: "Options"
 draft: false
 ---
 
-Options are instructions to translators on how a particular 
+Options are instructions to translators on how a particular
 definition should be regarded. Any translator can make use of any
-option. Options can take a list of string arguments much like the 
-options and arguments to a program. If none are specified, the option is 
-considered to be a Boolean value that is `true` if specified.
+option. Options can take a list of string arguments much like the
+options and arguments to a program. If none are specified, the
+option is considered to be a Boolean value that is `true` if
+specified.
 
-Every [vital definition](vital.md) in RIDDL allows a
-`technology` option that takes any number of string arguments. These can
-specify the technologies intended for the implementation. This idea was
+Options appear in `with { }` metadata blocks, not inside a
+definition's body. The syntax is `option is` *option_name* with
+optional string arguments:
+
+```riddl
+entity Order is {
+  ???
+} with {
+  option is event-sourced
+  option is technology("Akka")
+}
+```
+
+Every [vital definition](vital.md) in RIDDL allows a `technology`
+option that takes any number of string arguments. These can specify
+the technologies intended for the implementation. This idea was
 adapted from a similar idea in
 [Simon Brown's](https://www.linkedin.com/in/simonbrownjersey/)
 [C4 Model For Software Architecture](https://c4model.com/#Notation).
 
-Other options are specific to the kind of vital definition. See the 
-vital definition's page for details on the options they take. Non-vital 
-definitions do not allow options. 
+Other options are specific to the kind of vital definition. See the
+vital definition's page for details on the options they take.
+Non-vital definitions do not allow options.
 
 ## Occurs In
-All [vital definitions](vital.md)
+
+[Metadata](metadata.md) blocks (`with { }`) on any
+[vital definition](vital.md).
 
 ## Contains
-Option values which are simple identifiers with an optional set of string 
-arguments.
+
+Option values which are simple identifiers with an optional set of
+string arguments.