Add strategic site improvements for conversion and discovery

Phase 1 implementation to improve visitor engagement:
- 5-minute quickstart tutorial for new users
- Example models gallery linking to riddl-models repo
- Playground placeholder page for future interactive editor
- SEO meta descriptions on key pages
- Edit links for community contributions
- PWA/offline support via service worker
- Expanded About page with company story

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

Author: respencer-ncl

CLAUDE.md

@@ -18,6 +18,8 @@ ossum.tech/
 │   │   ├── introduction/    # What is RIDDL, why it exists
 │   │   ├── concepts/        # RIDDL language concepts (domain, context, etc.)
 │   │   ├── guides/          # User guides by role (authors, domain experts, etc.)
+│   │   ├── examples/        # Model gallery linking to riddl-models repo
+│   │   ├── playground/      # Interactive RIDDL editor (coming soon)
 │   │   ├── references/      # Language reference and EBNF grammar
 │   │   ├── tools/           # Documentation for riddlc, IDE plugins, etc.
 │   │   └── future-work/     # Planned features and roadmap
@@ -96,12 +98,15 @@ dark and light themes.
 ### MkDocs Configuration
 
 The site uses MkDocs Material theme with these notable features:
-- Automatic light/dark mode
+- Automatic light/dark mode with visible toggle
 - Navigation tabs
 - Search with highlighting
 - Admonitions (info boxes, warnings, etc.)
 - Code highlighting via Pygments with custom RIDDL lexer
 - Custom CSS in `docs/stylesheets/`
+- **Edit links** - Each page links to GitHub for community contributions
+- **PWA/offline support** - Service worker caches pages for offline access
+- **SEO meta descriptions** - Key pages have frontmatter descriptions
 
 ### Markdown Extensions
 
@@ -286,6 +291,7 @@ This documentation site covers tools from other Ossum Inc. repositories:
 - **riddl-idea-plugin**: IntelliJ IDEA plugin for RIDDL
 - **riddl-vscode**: VS Code extension for RIDDL (source for lexer tokens)
 - **riddl-mcp-server**: MCP server for AI-assisted RIDDL modeling
+- **riddl-models**: Curated example models (linked from `docs/riddl/examples/`)
 
 Refer to the parent `../CLAUDE.md` for cross-project coordination guidance.
 

NOTEBOOK.md

@@ -5,10 +5,13 @@
 Documentation site is complete and deployed at https://ossum.tech. All major
 sections are documented with proper RIDDL syntax highlighting.
 
-**Recent completion (2026-01-28):**
-- RIDDL Pygments lexer with custom color scheme matching IDE tools
-- Comprehensive editorial review of all documentation sections
-- CI workflow updated to install lexer before building
+**Completed (2026-01-28):**
+
+- Strategic site improvements Phase 1 (quickstart, examples gallery, SEO,
+  edit links, PWA support, about page, playground placeholder)
+- RIDDL Pygments lexer with custom color scheme
+- Comprehensive editorial review
+- CI workflow with lexer installation
 
 ---
 
@@ -20,13 +23,35 @@ sections are documented with proper RIDDL syntax highlighting.
 |------|-------|
 | Replace `{{MCP_SERVER_URL}}` | When public URL is available |
 | Update release download links | When final releases are published |
+| Implement playground | Integrate Monaco + MCP server validation |
+
+### Deferred Strategic Improvements (Soon)
+
+| ID | Task | Priority | Notes |
+|----|------|----------|-------|
+| 1.3 | Product landing pages by role | Medium | CTO, Architect, Developer pages |
+| 1.4 | Comparison pages | Medium | RIDDL vs OpenAPI/AsyncAPI/UML |
+| 1.5 | Demo video | High | 3-5 min screen recording with voiceover |
+| 2.2 | Troubleshooting/FAQ | Medium | Seed from riddl-mcp-server idioms |
+| 2.3 | Changelog links | Low | Link to GitHub releases |
+| 2.4 | Learning paths | Medium | Beginner → Intermediate → Advanced |
+| 2.5 | Mermaid diagrams | Low | Enable in mkdocs.yml, add to concepts |
+| 3.3 | Social proof | Medium | Testimonials when available |
+| 3.4 | Newsletter signup | Low | Mailchimp/ConvertKit embed |
+| 4.1 | Community (Discord/GH) | Medium | GitHub Discussions or Discord |
+| 4.4 | Page feedback | Low | "Was this helpful?" buttons |
+| 5.2 | PDF export | Low | mkdocs-pdf plugin |
+| 5.3 | API documentation | Medium | OpenAPI spec for MCP server |
+| 6.2 | Pricing page | Medium | When Synapify pricing finalized |
+| 6.3 | Contact form | Low | Replace email link with form |
+
+**Note:** Blog/news (3.2) will be on www.ossuminc.com or LinkedIn, not here.
 
 ### Lower Priority
 
 | Task | File | Notes |
 |------|------|-------|
 | Type examples | `references/language-reference.md` | Add specialized examples |
-| Quick-start tutorial | New file | Optional getting started guide |
 | Future work review | `future-work/` | Update for current roadmap |
 | EBNF grammar validation | `references/ebnf-grammar.md` | See details below |
 | Synapify generation docs | `synapify/generation.md` | Use preserved config |

docs/MCP/index.md

@@ -1,3 +1,9 @@
+---
+title: "RIDDL MCP Server"
+description: >-
+  Connect AI assistants to RIDDL via the Model Context Protocol. Enable
+  validation, analysis, and intelligent suggestions for domain modeling.
+---
 # RIDDL MCP Server
 
 The RIDDL MCP Server is a Model Context Protocol (MCP) server that enables

docs/OSS/index.md

@@ -1,3 +1,9 @@
+---
+title: "Open Source Tools"
+description: >-
+  Free and open source tools for RIDDL development. IDE extensions for
+  IntelliJ and VS Code, authoring guides, and MCP server integration.
+---
 # Ossum Open Source Software
 
 Ossum Inc. provides open source tools for working with the RIDDL language.

docs/about/index.md

@@ -1,5 +1,85 @@
 ---
-title: "About"
+title: "About Ossum Inc."
+description: >-
+  Learn about Ossum Inc., the company behind RIDDL and the mission to make
+  distributed system design accessible to everyone.
 ---
+# About Ossum Inc.
+
+**Ossum Inc.** builds tools that make designing distributed systems accessible
+to domain experts—not just seasoned architects.
+
+---
+
+## Our Mission
+
+Complex software systems are hard to build. The gap between what business
+experts understand and what developers implement is where projects fail.
+Requirements get lost in translation, designs drift from intent, and systems
+end up solving yesterday's problems.
+
+We believe there's a better way.
+
+**RIDDL** (Reactive Interface to Domain Definition Language) bridges this gap
+by providing a specification language that domain experts can read and
+contribute to, while being precise enough for AI-assisted code generation.
+It's Domain-Driven Design made practical.
+
+---
+
+## The Story
+
+RIDDL began in 2019, born from decades of experience building large-scale
+distributed systems. After watching project after project struggle with the
+same problems—miscommunication between business and technical teams, designs
+that couldn't keep up with changing requirements, implementations that drifted
+from specifications—founder Reid Spencer started asking: *What if the
+specification itself was the source of truth?*
+
+The first commits landed in late 2021. Reactific Software LLC, the original
+home of RIDDL, was acquired by Ossum Inc. in 2022 to continue the vision:
+making distributed system design accessible to everyone who understands the
+domain, not just those who can write code.
+
+---
+
+## What We Build
+
+### Open Source
+
+- **[RIDDL](../riddl/index.md)** – The specification language and compiler
+- **[IDE Extensions](../OSS/index.md)** – VS Code and IntelliJ support
+- **[Synapify](../synapify/index.md)** – Professional modeling workbench with
+  visual editing, simulation, and code generation
+
+### Commercial
+
+- **[MCP Server](../MCP/index.md)** – AI assistant integration
+
+---
+
+## The Team
+
+RIDDL exists because of the contributions of many, but it was initiated by:
+
+**Reid Spencer** - Founder & Chief Architect
+:   Deeply experienced system architect, software developer, and entrepreneur.
+    Initiated RIDDL in 2019 and founded Ossum Inc. to bring it to market.
+    [LinkedIn](https://www.linkedin.com/in/reidspencer)
+
+See [Who Made RIDDL Possible](../riddl/introduction/who-made-riddl-possible.md)
+for the full list of contributors and the foundational work RIDDL builds upon.
+
+---
+
+## Contact
+
+- **Support**: support@ossuminc.com
+- **GitHub**: [github.com/ossuminc](https://github.com/ossuminc)
+- **LinkedIn**: [linkedin.com/company/ossum-inc](https://www.linkedin.com/company/ossum-inc/)
+
+---
+
+## Legal
 
 - [Privacy Policy](privacy-policy.md)

docs/index.md

@@ -1,7 +1,10 @@
 ---
-title: "Ossum!"
+title: "Ossum Technologies"
+description: >-
+  Documentation for RIDDL, a specification language for distributed reactive
+  systems. Explore tools, guides, and references for domain-driven design.
 ---
-# Welcome To Ossum Technology!
+# Welcome To Ossum Inc.'s Technology!
 
 This site provides documentation for technologies created at Ossum, Inc.