Continue editorial review: concepts section and session docs

Concepts section fixes:
- Remove Hugo shortcode from index.md ({{< toc-tree >}})
- Fix icon syntax in domain.md (Hugo → Font Awesome)
- Fix "an user" → "a user" grammar
- Fix missing apostrophe and punctuation in context.md

Session documentation:
- CLAUDE.md: Add Editorial Guidelines section with learnings
- NOTEBOOK.md: Update with 2026-01-27 session progress

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

Author: respencer-ncl

CLAUDE.md

@@ -241,4 +241,88 @@ Refer to the parent `../CLAUDE.md` for cross-project coordination guidance.
 | Start dev server | `mkdocs serve` |
 | Build site | `mkdocs build` |
 | Check links | `mkdocs build --strict` |
-| Deploy | `mkdocs gh-deploy` |
+| Deploy | `mkdocs gh-deploy` |
+
+---
+
+## Editorial Guidelines (Session Learnings)
+
+These guidelines were established during documentation review sessions:
+
+### Tooling Separation
+
+**Important**: The RIDDL ecosystem has a clear separation of concerns:
+
+- **`riddlc`** (open source): Syntax and semantic validation only. It reads
+  RIDDL files, checks them, and reports errors. No code generation.
+- **Synapify** (commercial): Provides advanced features including code
+  generation, documentation generation, and AI-assisted development. These
+  features are available via subscription.
+
+When documenting capabilities, do NOT claim that `riddlc` generates code,
+diagrams, Kubernetes manifests, etc. Those capabilities exist in Synapify.
+Avoid mentioning "riddl-gen" directly—it's an internal service name. Just
+refer to Synapify's generation features.
+
+### Outdated Technology References
+
+Remove or generalize references to specific generation targets that are no
+longer accurate:
+
+- ~~Kalix~~ (no longer a target)
+- ~~Kubernetes deployment descriptors~~ (not in OSS tooling)
+- ~~Akka code generation~~ (not in OSS tooling)
+- ~~Protocol Buffers / Smithy / OpenAPI generation~~ (not in OSS tooling)
+
+Instead, describe RIDDL's *capability* to enable such translation without
+claiming specific tool support.
+
+### Hugo Remnants
+
+This site migrated from Hugo to MkDocs Material. Remove any Hugo shortcodes:
+
+- `{{< toc-tree >}}` — doesn't work in MkDocs
+- `{{< icon "..." >}}` — use Font Awesome syntax or remove
+- Any other `{{< ... >}}` patterns
+
+### Capitalization
+
+Always use **RIDDL** (all caps) in prose. It's an acronym. Not "Riddl" or
+"riddl" except in code/filenames where lowercase is conventional.
+
+### RIDDL Syntax in Examples
+
+Code examples must match the EBNF grammar. Common issues to avoid:
+
+1. **Missing `is` keyword**: Most definitions require it.
+   - Wrong: `on command Foo { ... }`
+   - Right: `on command Foo is { ... }`
+
+2. **User stories require both parts**:
+   - Right: `user Customer wants to "do X" so that "Y happens"`
+
+3. **Epics and use cases start with user stories**:
+   ```riddl
+   epic Shopping is {
+     user Customer wants to "..." so that "..."
+     case AddToCart is { ... }
+   }
+   ```
+
+4. **Step interactions use specific syntax**:
+   - `step for user Customer is "does something"`
+   - `step send command X from user Y to entity Z`
+   - `step show output X to user Y`
+
+### Tone and Style
+
+- Light, accessible, occasionally jovial
+- Technical precision without being dry
+- Explain concepts before showing syntax
+- Use em-dashes for asides—they read more naturally
+- Prefer active voice
+
+### Known Authors (Correct Spellings)
+
+For the Reactive Manifesto: Jonas Bonér, **Dave** Farley (not David),
+Roland **Kuhn** (not Kunh), Martin Thompson.

NOTEBOOK.md

@@ -13,6 +13,36 @@ All changes pushed to origin/main.
 
 ## Work Completed (Recent)
 
+### 2026-01-27: Documentation Editorial Review
+
+Grammar, style, spelling, and accuracy review of documentation:
+
+- [x] **Introduction Section** (9 files, committed)
+  - Fixed duplicate navigation list in index.md
+  - Standardized RIDDL capitalization throughout
+  - Updated what-can-riddl-do.md to reflect riddlc as validator only
+  - Fixed invalid RIDDL syntax in code examples (why-is-riddl-needed.md)
+  - Removed outdated technology references (Kalix, Kubernetes, etc.)
+  - Fixed typos: Branchs→Branches, Kuberenetes→Kubernetes, Roland Kunh→Kuhn
+  - Fixed broken anchor syntax and URLs
+  - Fixed missing words and broken markdown links
+
+- [x] **CLAUDE.md Updates**
+  - Added Editorial Guidelines section with session learnings
+  - Documented tooling separation (riddlc vs Synapify)
+  - Added guidance on outdated technology references
+  - 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:
@@ -130,7 +160,12 @@ Completed all 6 phases of the comprehensive documentation improvement:
 
 ## In Progress
 
-None currently.
+### 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)
 
 ## Pending Tasks
 

docs/riddl/concepts/context.md

@@ -51,15 +51,15 @@ on the same page.
 
 When modelling a system with RIDDL, the *ubiquitous language* boils down to
 the names of the definitions that RIDDL permits inside a `context` definition, as
-shown in the list below. You can correctly think of a `context`s ubiquitous
+shown in the list below. You can correctly think of a `context`'s ubiquitous
 language as the interface to that knowledge domain. It is very analogous to
 an API (Application Programming Interface) as the interface to a program. The API
 defines the contract for how external systems interact with the bounded context.
 
-To further your understanding, watch this 
+To further your understanding, watch this
 [34-minute video](https://www.youtube.com/watch?v=am-HXycfalo) by
-[Eric Evans](../introduction/who-made-riddl-possible.md#eric-evans) 
-from DDD Europe 2020 conference
+[Eric Evans](../introduction/who-made-riddl-possible.md#eric-evans)
+from DDD Europe 2020 conference.
 
 
 ## Occurs In

docs/riddl/concepts/domain.md

@@ -35,15 +35,15 @@ might devise a domain hierarchy like this:
 ## Occurs In
 
 * [Root](root.md)
-* [Domains](domain.md) {{< icon "rotate-left - domains
-  can be nested in a super-domain.
+* [Domains](domain.md) :fontawesome-regular-rotate-left: — domains
+  can be nested in a super-domain
 
 ## Contains
 
 Within a domain, you can define these things:
 
 * [Actors](user.md) - someone or thing that uses the domain
-* [Applications](application.md) - an user interface  
+* [Applications](application.md) - a user interface  
 * [Authors](author.md) - who defined the domain
 * [Contexts](context.md) - a precisely defined bounded context within the domain
 * [Domains](domain.md) :fontawesome-regular-rotate-left: - domains 

docs/riddl/concepts/index.md

@@ -105,4 +105,5 @@ When you're done exploring all the concepts, check out our
 
 ## Full Index
 
-{{< toc-tree >}}
+The pages in this section cover each RIDDL concept in detail. Use the
+navigation menu to explore individual concepts.