docs: unify README with the shared skeleton and expand the org profile

README.md

@@ -1,19 +1,61 @@
+<div align="center">
+
+<img src="https://mux-lang.dev/img/mux-logo.png" alt="Mux Logo" width="120">
+
 # .github
 
-Organization-level defaults for the [muxlang](https://github.com/muxlang) org:
+**Organization-level defaults for the [muxlang](https://github.com/muxlang) org**
+
+[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
+[![Sonar Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=muxlang_.github&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=muxlang_.github)
+
+</div>
+
+Shared community-health files, the org profile, and the canonical sources that
+sync labels and issue templates into every repo.
+
+---
+
+## What's here
+
+| Path | What it is |
+|------|------------|
+| `profile/README.md` | The org profile shown on the [organization page](https://github.com/muxlang) |
+| `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` | Shared community-health defaults |
+| `labels/` | Canonical label YAML and per-repo overlays |
+| `templates/<repo>/` | Canonical issue template sources synced to each repo |
+| `scripts/sync-labels.sh` | Apply label YAML to org repos (`gh` CLI required) |
+| `scripts/sync-templates.sh` | Copy `templates/<repo>/` into a repo checkout |
+| `scripts/validate-labels.py` | Diff live labels against the canonical YAML; exits nonzero on drift |
+
+---
 
-- `profile/README.md` - the org profile shown on the [organization page](https://github.com/muxlang).
-- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` - shared community-health defaults.
-- `labels/` - canonical label YAML and per-repo overlays.
-- `templates/<repo>/` - canonical issue template sources synced to each repo.
-- `scripts/sync-labels.sh` - apply label YAML to org repos (`gh` CLI required).
-- `scripts/sync-templates.sh` - copy `templates/<repo>/` into a repo checkout.
-- `scripts/validate-labels.py` - diff live labels against the canonical YAML;
-  exits nonzero on drift (run after any sync).
+## How syncing works
+
+Per-repo `.github/ISSUE_TEMPLATE/`, `.github/workflows/issue-triage.yml`, and
+`.github/labels.yml` are synced from `templates/` here via
+`scripts/sync-templates.sh`. Do not copy templates or invent labels in individual
+repos - change them here and re-sync.
 
 Policy and workflow rules:
 [mux-context/docs/repo-governance.md](https://github.com/muxlang/mux-context/blob/main/docs/repo-governance.md).
 
-Per-repo `.github/ISSUE_TEMPLATE/`, `.github/workflows/issue-triage.yml`, and
-`.github/labels.yml` are synced from `templates/` here via `scripts/sync-templates.sh`.
-Do not copy templates or invent labels in individual repos.
+---
+
+## Related repositories
+
+| Repo | What it is |
+|------|------------|
+| [mux-compiler](https://github.com/muxlang/mux-compiler) | The language, compiler, and CLI (the canonical Mux version) |
+| [mux-runtime](https://github.com/muxlang/mux-runtime) | Runtime + standard library linked by compiled programs |
+| [mux-website](https://github.com/muxlang/mux-website) | Docs site (mux-lang.dev) and playground UI |
+| [mux-website-api](https://github.com/muxlang/mux-website-api) | Compile/run API behind the playground |
+| [tree-sitter-mux](https://github.com/muxlang/tree-sitter-mux) | Tree-sitter grammar + highlight queries |
+| [mux-syntax-highlighting](https://github.com/muxlang/mux-syntax-highlighting) | TextMate grammar, VSCode extension, canonical syntax spec |
+| [mux-context](https://github.com/muxlang/mux-context) | Cross-repo architecture, design rationale, glossary, releases |
+
+---
+
+## License
+
+[MIT](LICENSE) - Maintained by [Derek Corniello](https://github.com/DerekCorniello)

profile/README.md

@@ -1,14 +1,69 @@
+<div align="center">
+
+<img src="https://mux-lang.dev/img/mux-logo.png" alt="Mux Logo" width="140">
+
 # Mux
 
-**The programming language for everyone.** Mux is a statically-typed,
-reference-counted language that combines Python's readability, Go's simplicity, and
-Rust's type safety, compiled to native code via LLVM.
+### The programming language for everyone
+
+Mux is a statically-typed, reference-counted language that combines Python's
+readability, Go's simplicity, and Rust's type safety - compiled to native code
+via LLVM.
+
+[![Website](https://img.shields.io/badge/mux--lang.dev-visit-2ea6ff.svg?style=flat-square)](https://mux-lang.dev)
+[![Docs](https://img.shields.io/badge/docs-read-blue.svg?style=flat-square)](https://mux-lang.dev/docs/getting-started/quick-start)
+[![Playground](https://img.shields.io/badge/playground-try%20online-orange.svg?style=flat-square)](https://mux-lang.dev/playground)
+[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](https://github.com/muxlang/mux-compiler/blob/main/LICENSE)
+
+</div>
+
+---
+
+## A first taste
+
+```mux
+// Error handling with Result types
+func divide(int a, int b) returns result<int, string> {
+    if b == 0 {
+        return err("division by zero")
+    }
+    return ok(a / b)
+}
 
-- **Website & docs:** [mux-lang.dev](https://mux-lang.dev)
-- **Install:** `curl -fsSL https://raw.githubusercontent.com/muxlang/mux-compiler/main/scripts/install.sh | sh`
-- **Try it online:** the playground at [mux-lang.dev](https://mux-lang.dev)
+// Pattern matching with exhaustive checking
+func main() returns void {
+    match divide(10, 2) {
+        ok(value) {
+            print("Result: " + value.to_string())
+        }
+        err(error) {
+            print("Error: " + error)
+        }
+    }
+}
+```
 
-## Repositories
+## Get started
+
+```bash
+# Install (Linux/macOS)
+curl -fsSL https://raw.githubusercontent.com/muxlang/mux-compiler/main/scripts/install.sh | sh
+
+# Run your first program
+mux run hello.mux
+```
+
+Or skip the install and **[try it in the playground](https://mux-lang.dev/playground)**.
+
+## Why Mux?
+
+- **Simple & readable** - clean, semicolon-free syntax with Python-like clarity.
+- **Type safe** - strong static typing, no implicit conversions, errors caught at compile time.
+- **Fast & native** - LLVM-powered compilation to real native binaries.
+- **Memory safe** - reference counting, no GC pauses and no borrow-checker ceremony.
+- **Modern** - generics, interfaces, tagged unions, and exhaustive pattern matching.
+
+## The repositories
 
 | Repo | What it is |
 |------|------------|
@@ -22,11 +77,15 @@ Rust's type safety, compiled to native code via LLVM.
 
 ## Getting involved
 
-- New to the language? Start with the [docs](https://mux-lang.dev).
-- Want to understand how it fits together? See [muxlang/mux-context](https://github.com/muxlang/mux-context).
-- Want to contribute? Each repo has its own `README.md` and `AGENTS.md`; shared
-  contribution guidelines live in this repo's `CONTRIBUTING.md`.
-- Found a bug or have an idea? Open an issue in the relevant repo - or, if you're
-  unsure which one, in [mux-context](https://github.com/muxlang/mux-context/issues) for triage.
+- **New to the language?** Start with the [docs](https://mux-lang.dev).
+- **Curious how it fits together?** Read [mux-context](https://github.com/muxlang/mux-context).
+- **Want to contribute?** Each repo has its own `README.md` and `AGENTS.md`; shared
+  guidelines live in [CONTRIBUTING.md](https://github.com/muxlang/.github/blob/main/CONTRIBUTING.md).
+- **Found a bug or have an idea?** Open an issue in the relevant repo - or, if
+  you're unsure which, in [mux-context](https://github.com/muxlang/mux-context/issues) for triage.
+
+<div align="center">
 
 Mux is MIT-licensed and welcomes contributions.
+
+</div>