Complete documentation editorial review

Major changes across 40 files:

Concepts section (26 files):
- Rewrote application.md: clarified applications are contexts with groups
- Rewrote processor.md: explained abstract concept and concrete types
- Fixed RIDDL syntax: any of vs one of for enumerations
- Changed Actor→User terminology per Use Cases 2.0
- Fixed numerous typos, grammar, and broken links
- Removed unimplemented features (Subscriptions in connector.md)

Guides section (7 files):
- Updated riddlc references to validation-only
- Added Synapify links for documentation/code generation
- Fixed JDK 21→25, Scala 3.6.x→3.3.x LTS versions
- Fixed sbt stage→sbt riddlc/stage commands
- Removed outdated Hugo command references

Tools section (3 files):
- Updated riddlc capabilities to validation-only
- Removed hugo command documentation
- Updated HOCON config examples for validate command

OSS section (2 files):
- Fixed enumeration syntax in authoring guide
- Updated JDK version requirements

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

Author: respencer-ncl

NOTEBOOK.md

@@ -13,6 +13,69 @@ All changes pushed to origin/main.
 
 ## Work Completed (Recent)
 
+### 2026-01-28: Documentation Editorial Review (Continued)
+
+Comprehensive editorial review of all documentation sections:
+
+- [x] **Concepts Section** (all files reviewed and fixed)
+  - adaptor.md: Added missing "from", fixed link spacing
+  - application.md: Complete rewrite - clarified applications are contexts with groups
+  - case.md: Fixed "too"→"to" typo
+  - connector.md: Removed unimplemented Subscriptions section
+  - constant.md: Simplified to reference vital.md
+  - definition.md: Removed outdated Hugo reference
+  - description.md: Removed Hugo formatter reference
+  - element.md: Fixed "Occurs In" and self-reference issues
+  - entity.md: Fixed actor→user model, Eric Brewer, event-sourced hyphenation
+  - epic.md: Fixed "an user"→"a user" (3 instances)
+  - function.md: Fixed wrong handler link
+  - group.md: Fixed broken Hugo icon shortcode
+  - handler.md: Fixed Projection→Projector
+  - interaction.md: Fixed "an Use Case"→"a Use Case"
+  - message.md: Removed duplicate application line, fixed principal→principle,
+    Projections→Projectors
+  - onclause.md: Fixed receipient→recipient, whenthe→when the
+  - option.md: Fixed link spacing, added missing period
+  - output.md: Fixed "an user"→"a user"
+  - processor.md: Complete rewrite explaining abstract concept and concrete types
+  - projector.md: Fixed projections→projectors
+  - repository.md: Fixed wrong anchor links (#query→#command, #result→#event)
+  - sagastep.md: Fixed examples→clauses
+  - type.md: Fixed Hugo TOC shortcode, RIDDL syntax (any of/one of)
+  - user.md: Changed Actor→User per Use Cases 2.0 terminology
+  - vital.md: Fixed truncation, removed Applications, added Streamlets
+
+- [x] **Guides Section** (all files reviewed and fixed)
+  - authors/index.md: Fixed event-sourced hyphenation, updated doc generation
+    to reference Synapify
+  - developers/index.md: Updated JDK 21→25, Scala 3.6.x→3.3.x LTS, noted hugo
+    migration to Synapify, fixed sbt stage→sbt riddlc/stage
+  - domain-experts/duties.md: Fixed "context or"→"context of"
+  - domain-experts/index.md: Replaced Hugo toc-tree shortcode
+  - domain-experts/relating-to-riddl.md: Fixed Riddl→RIDDL in title
+  - implementors/index.md: Replaced Hugo toc-tree shortcode
+  - implementors/ways-to-use-riddl.md: Fixed sbt stage commands, updated HOCON
+    example for validate-only, removed hugo references, added Synapify links
+
+- [x] **Tools Section** (all files reviewed and fixed)
+  - index.md: Updated riddlc description to validation-only, added Synapify link
+  - riddlc/index.md: Fixed sbt stage, removed hugo command sections, updated
+    HOCON config to use common section, added Synapify links
+  - riddl-idea-plugin/index.md: Updated JDK 21→25
+  - riddl-mcp-server/index.md: Clean, no issues
+
+- [x] **OSS Section** (all files reviewed and fixed)
+  - authoring-riddl.md: Fixed "one of"→"any of" for enumerations (2 instances)
+  - intellij-plugin/index.md: Updated JDK 21→25
+  - vscode-extension/index.md: Clean, no issues
+  - index.md: Clean, no issues
+
+- [x] **MCP Section** (all files reviewed)
+  - All files clean, no issues found
+
+- [x] **References Section** (reviewed)
+  - index.md: Clean, no issues
+
 ### 2026-01-27: Documentation Editorial Review
 
 Grammar, style, spelling, and accuracy review of documentation:
@@ -34,15 +97,6 @@ Grammar, style, spelling, and accuracy review of documentation:
   - Added Hugo remnant removal guidance
   - Documented RIDDL syntax validation rules for examples
 
-- [ ] **Concepts Section** (in progress, 3 files uncommitted)
-  - Fixed Hugo shortcode in index.md
-  - Fixed icon syntax and grammar in domain.md
-  - Fixed apostrophe and punctuation in context.md
-
-**Pending for next session:**
-- entity.md: "user model" → "actor model", "Erik" → "Eric" Brewer, typos
-- Continue through remaining ~85 concept and other files
-
 ### 2026-01-26: Synapify User Guide Expansion
 
 Comprehensive expansion of Synapify documentation based on product discussion:
@@ -160,12 +214,7 @@ Completed all 6 phases of the comprehensive documentation improvement:
 
 ## In Progress
 
-### Documentation Editorial Review
-- Reviewing all docs/ markdown files for grammar, style, accuracy
-- Validating RIDDL syntax examples against EBNF grammar
-- Removing outdated technology references
-- Ensuring consistent tone (light, accessible, technically precise)
-- **Next**: Continue with concepts section (entity.md and beyond)
+Editorial review complete. All sections reviewed and fixed. Ready to commit.
 
 ## Pending Tasks
 
@@ -180,9 +229,69 @@ Completed all 6 phases of the comprehensive documentation improvement:
 
 | Task | File | Notes |
 |------|------|-------|
+| RIDDL Pygments lexer | New file | Custom syntax highlighting for code blocks |
 | Type examples | `references/language-reference.md` | Add specialized examples |
 | Future work review | `future-work/` | Update for current roadmap |
 | Quick-start tutorial | New file | Optional getting started guide |
+| EBNF grammar validation | `references/ebnf-grammar.md` | See details below |
+
+#### Synapify Generation Configuration Documentation
+
+When documenting Synapify's documentation/code generation features, use this
+HOCON configuration example as a starting point (preserved from riddlc hugo):
+
+```hocon
+hugo {
+    input-file = "ReactiveBBQ.riddl"
+    output-dir = "target/hugo/ReactiveBBQ"
+    project-name = "Reactive BBQ"
+    site-title = "Reactive BBQ Generated Specification"
+    site-description = "Generated specification for the Reactive BBQ application"
+    site-logo-path = "images/RBBQ.png"
+    erase-output = true
+    base-url = "https://bbq.riddl.tech"
+    source-url = "https://github.com/ossuminc/riddl"
+    edit-path = "/-/blob/main/src/riddl/ReactiveBBQ"
+}
+```
+
+#### RIDDL Pygments Lexer Task
+
+Create a custom Pygments lexer for RIDDL syntax highlighting in MkDocs code
+blocks. Currently `riddl` fenced code blocks render without syntax coloring.
+
+**Implementation approach:**
+1. Create `riddl_lexer.py` with a `RiddlLexer` class extending `RegexLexer`
+2. Define token patterns for RIDDL keywords, types, strings, comments, etc.
+3. Register the lexer in `mkdocs.yml` or via a plugin
+4. Test with existing code examples in documentation
+
+**Key token categories:**
+- Keywords: `domain`, `context`, `entity`, `handler`, `type`, `command`,
+  `event`, `query`, `result`, `is`, `of`, `to`, `from`, `inlet`, `outlet`, etc.
+- Predefined types: `String`, `Number`, `Boolean`, `Date`, `Time`, `UUID`, etc.
+- Operators: `=`, `:`, `{`, `}`, `(`, `)`, `[`, `]`
+- Comments: `//` line comments, `/* */` block comments
+- Strings: quoted literals
+
+#### EBNF Grammar Validation Task
+
+The EBNF grammar (`docs/riddl/references/ebnf-grammar.md`) is derived from the
+official fastparse grammar in the riddl module and is intended for AI tools to
+quickly understand RIDDL syntax. It must accurately reflect the rules accepted
+by the fastparse parser.
+
+**Known discrepancies found during editorial review:**
+- Missing `=` as alternative to `is` in type definitions
+- Missing `:` as alternative to `is` in field definitions (Scala-style syntax)
+
+**Validation approach:**
+1. Create a functional parser from the EBNF grammar
+2. Run it against all example RIDDL sources in the test suite
+3. Compare results with the fastparse parser
+4. Revise EBNF until there are no discrepancies
+
+This ensures the EBNF remains a reliable reference for AI-assisted RIDDL work.
 
 ## Design Decisions Log
 

docs/OSS/authoring-riddl.md

@@ -171,7 +171,7 @@ Define domain-specific types:
 type OrderId is Id(Order)
 
 // Enumeration
-type OrderStatus is one of { Pending, Confirmed, Shipped, Delivered, Cancelled }
+type OrderStatus is any of { Pending, Confirmed, Shipped, Delivered, Cancelled }
 
 // Aggregation (record)
 type Address is {
@@ -182,8 +182,8 @@ type Address is {
   country: String
 }
 
-// Alternation (union)
-type PaymentMethod is one of {
+// Enumeration
+type PaymentMethod is any of {
   CreditCard, DebitCard, BankTransfer, DigitalWallet
 }
 ```

docs/OSS/intellij-plugin/index.md

@@ -34,7 +34,7 @@ Marketplace:
 ### Requirements
 
 - IntelliJ IDEA 2024.1 or later (Community or Ultimate Edition)
-- JDK 21 or later
+- JDK 25 or later
 
 ---
 

docs/riddl/concepts/adaptor.md

@@ -5,17 +5,17 @@ draft: false
 
 An adaptor's purpose is to _adapt_ one [Context](context.md)
 to another [Context](context.md).  In Domain-Driven Design, 
-this concept is known as an _anti-corruption layer_ that keeps the 
-ubiquitous language of one context "corrupting" the language of another 
+this concept is known as an _anti-corruption layer_ that keeps the
+ubiquitous language of one context from "corrupting" the language of another 
 context.  The authors of RIDDL didn't like that term for a variety of reasons
 so we have renamed the concept as _adaptor_ in RIDDL. Same idea, different name.
 
 ## Message Translation
 Adaptors do their work at the level of messages sent between 
-[Contexts](context.md). This is done using one or 
-more [Handlers]( handler.md ). Each handler specifies 
-how messages are translated into other messages and forwarded to the target 
-[context](context.md).   
+[Contexts](context.md). This is done using one or
+more [Handlers](handler.md). Each handler specifies 
+how messages are translated into other messages and forwarded to the target
+[context](context.md).
 
 ## Target Context
 Adaptors are only definable within a containing 

docs/riddl/concepts/application.md

@@ -3,47 +3,44 @@ title: "Application"
 draft: false
 ---
 
-An application in RIDDL is represented by a [Context](context.md) that has
-[Group](group.md)s in its definition. represents an interface 
-portion of a system where an 
-user (human or machine) initiates an action on the system. Applications 
-only define the net result of the interaction between the user and the 
-application. They are abstract on purpose. That is, there is nothing in RIDDL 
-that defines how information is provided to a user nor received from a user. 
-This gives free latitude to the user interface 
-designer to manage the entire interaction between human and machine. 
-
-There are also no assumptions about the technology used for the 
-implementation of an application. RIDDL's notion of an application is general
-and abstract, but they can be implemented as any of the following:
+An application in RIDDL is not a separate definition type—it is simply a
+[Context](context.md) that contains [Group](group.md)s. When a context has
+groups, it represents an interface portion of a system where a user (human
+or machine) initiates actions.
+
+Applications only define the net result of the interaction between the user
+and the system. They are abstract on purpose. There is nothing in RIDDL that
+defines how information is provided to a user or received from a user. This
+gives free latitude to the user interface designer to manage the entire
+interaction between human and machine.
+
+There are also no assumptions about the technology used for implementation.
+RIDDL's notion of an application is general and abstract, but can be
+implemented as any of the following:
 
 * Mobile Application On Any Platform
 * Web Application
 * Native Operating System Application (graphical or command line)
 * Interactive Voice Recognition
 * Virtual Reality with Haptics
-* and other things yet to be invented. 
+* and other things yet to be invented
 
-This means a RIDDL application specification can be used as the basis for 
-creating multiple implementations of the specification using a variety of 
-technologies.     
+This means a RIDDL application specification can be used as the basis for
+creating multiple implementations using a variety of technologies.
 
 ## Groups
-Applications abstractly design a user interface by containing a set of 
-[groups](group.md). Groups can be nested which allows them
-to define the structure of a user interface. 
+
+Applications abstractly design a user interface by containing a set of
+[groups](group.md). Groups can be nested, which allows them to define the
+hierarchical structure of a user interface.
 
 ## Handlers
-Applications have message [handlers](handler.md) like many other RIDDL definitions. 
-However, application handlers only receive their messages from [actors](user.md), 
-unlike other handlers. Typically, the handling of messages in handlers will 
-ultimately send further messages to other components, like a [context](context.md) or
-[entity](entity.md)
-
-## Occurs In
-* [Domain](domain.md)
-
-## Contains
-* [Type](type.md)
-* [Group](element.md)
-* [Handler](handler.md)
+
+Application contexts have message [handlers](handler.md) like other contexts.
+These handlers receive messages from [users](user.md) and typically forward
+messages to other components like [entities](entity.md).
+
+## See Also
+
+* [Context](context.md) — The definition type used to model applications
+* [Group](group.md) — UI structure within application contexts

docs/riddl/concepts/case.md

@@ -22,9 +22,9 @@ The following table shows the pairings recognized:
 | subscribe |  any  |  pipe   | Subscribe to a pipe                         |
 |   saga    |  any  |  saga   | Initiate a saga                             |
 |  select   | user | element | Select an item from application element     |
-|  provide  | user | element | Provide input data too application          |
+|  provide  | user | element | Provide input data to application           |
 |  present  | user | element | Cause an application to present info        |
- 
+
 
 ## Occurs In
 * [Epic](epic.md)

docs/riddl/concepts/connector.md

@@ -80,29 +80,17 @@ connecting two pipes together. Producers provide the data, consumers consume
 the data. Sometimes we call producers *sources* because they originate the data.
 Sometimes we call consumers *sinks* because they terminate the data.
 
-{{< mermaid align="left" >}}
+```mermaid
 graph LR;
 Producers --> P{{Pipe}} --> Consumers
 Source --> P1{{Pipe 1}} --> Flow --> P2{{Pipe 2}} --> Sink
-{{< /mermaid >}}
+```
 
 Pipes may have multiple publishers (writers of data to the pipe) and multiple
 consumers (readers of data from the pipe). In fact, because of the
 _partitioned consumption_ principle, there can be multiple groups of consumers,
 each group getting each data item from the pipe.
 
-## Subscriptions
-
-{{< hint type=warning icon=gdoc_dangerous title="Not Implemented" >}}
-This feature is not implemented as of 0.16.1
-{{< /hint >}}
-
-When a pipe has multiple consumers, they are organized into subscriptions. 
-Each subscription gets every datum the pipe carries. Consumers attach to a
-subscription and there is generally one consumer per partition of the 
-subscription. Sometimes subscriptions are known as *consumer groups* as is the
-case for Kafka.
-
 ## Occurs In
 
 * [Streamlets](streamlet.md)

docs/riddl/concepts/constant.md

@@ -4,23 +4,11 @@ draft: false
 ---
 
 A constant is simply a definition that names an unchanging value. This is
-useful for modeling technical domains that utilize constant values
+useful for modeling technical domains that utilize constant values.
 
 ## Occurs In
 
-All [vital](vital.md) definitions may contain constants.
-
-* [Adaptors](adaptor.md),
-* [Applications](application.md),
-* [Contexts](context.md),
-* [Domains](domain.md),
-* [Functions](function.md),
-* [Entities](entity.md),
-* [Epic](epic.md).
-* [Processors](processor.md),
-* [Projectors](projector.md),
-* [Repositories](repository.md)
-* [Sagas](saga.md), and
+All [vital definitions](vital.md) may contain constants.
 
 ## Contains
 

docs/riddl/concepts/definition.md

@@ -20,8 +20,7 @@ All definitions have some common attributes:
   the documentation output and the glossary.
 * _description_: A block of
   [Markdown](https://www.markdownguide.org/getting-started/) that
-  fully describes the definition. All the facilities provided by the  
-  [hugo-geekdoc](https://geekdocs.de/) template for hugo are supported.
+  fully describes the definition.
 
 These attributes merely provide supplemental information about the
 definition but are not part of the definition.

docs/riddl/concepts/description.md

@@ -4,11 +4,9 @@ draft: false
 ---
 
 Descriptions describe definitions. You can add a description to any kind of
-definition. Descriptions are written in Markdown format and can include any
-of the capabilities provided by the
-[GeekDoc hugo formatter](https://geekdocs.de/usage/getting-started/)
-including [mermaid](https://mermaid-js.github.io/mermaid/#/README) 
-based diagrams. Descriptions can also be provided in separate files and via
+definition. Descriptions are written in Markdown format and can include
+[mermaid](https://mermaid-js.github.io/mermaid/#/README) diagrams and other
+Markdown features supported by the documentation renderer. Descriptions can also be provided in separate files and via
 public (no password required) HTTP URLs. 
 
 ## Occurs On