MLSysDev · HumbleBee14 · Jul 12, 2026 · Jul 12, 2026 · Jul 12, 2026 · Jul 12, 2026
diff --git a/.gitignore b/.gitignore
@@ -40,3 +40,6 @@ Thumbs.db
 
 # Roopik IDE metadata
 .roopik/
+
+# local AI design/planning docs — never committed
+docs/superpowers/
diff --git a/LICENSE b/LICENSE
@@ -1,44 +1,8 @@
 License
 =======
 
-This repository contains two different kinds of work, licensed differently.
-
-================================================================================
-1. CODE
-================================================================================
-
-The source code in this repository (everything outside `src/content/`,
-including all `.astro`, `.ts`, `.tsx`, `.js`, `.css`, and configuration files)
-is licensed under the MIT License:
-
-  MIT License
-
-  Copyright (c) 2026 mlsystems.dev contributors
-
-  Permission is hereby granted, free of charge, to any person obtaining a copy
-  of this software and associated documentation files (the "Software"), to deal
-  in the Software without restriction, including without limitation the rights
-  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-  copies of the Software, and to permit persons to whom the Software is
-  furnished to do so, subject to the following conditions:
-
-  The above copyright notice and this permission notice shall be included in
-  all copies or substantial portions of the Software.
-
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-  THE SOFTWARE.
-
-================================================================================
-2. CONTENT
-================================================================================
-
-All content in `src/content/` (blog posts, learning materials, diagrams,
-images, and other written work) is © its respective author.
+All content in this repository — blog posts, learning materials, diagrams,
+images, code samples, and other written work — is © its respective author.
 
 ALL RIGHTS RESERVED.
 
@@ -47,21 +11,21 @@ What this means in practice
 
 YOU ARE WELCOME TO:
 
-  - Read anything on the site
-  - Link to any URL on mlsystems.dev
-  - Share URLs on social media, Discord, in messages, anywhere
+  - Read anything published here
+  - Link to any post
+  - Share links on social media, Discord, in messages, anywhere
   - Quote brief excerpts (a sentence or short paragraph) with attribution
     and a link back to the original, for commentary, criticism, teaching,
     research, slides, presentations, or news reporting — this is
     "fair use" / "fair dealing" under copyright law and does not require
     permission
-  - Cite our posts as references in your own work
+  - Cite posts as references in your own work
   - Translate a full post into another language, provided you:
       * Credit the original author by name
-      * Link back to the original post URL
+      * Link back to the original post
       * Make the translation freely readable (not paywalled)
-    We encourage translations — please share the translated URL with us
-    so we can link it from the original post.
+    We encourage translations — please share the translated link with us
+    so we can point to it from the original post.
 
 YOU MAY NOT, WITHOUT WRITTEN PERMISSION FROM THE AUTHOR:
 
@@ -79,20 +43,19 @@ YOU MAY NOT, WITHOUT WRITTEN PERMISSION FROM THE AUTHOR:
 
 For permission requests, contact the author or admin@mlsystems.dev.
 
-These rules apply site-wide. Individual posts cannot opt into a different
-license. If you are an author who wants different terms for a specific
-post, contact a maintainer.
+Individual posts cannot opt into a different license. If you are an author
+who wants different terms for a specific post, contact a maintainer.
 
 Community contributions
 -----------------------
 
-By submitting content (blog posts, edits, images, etc.) to this repository,
-you confirm that:
+By submitting content (blog posts, edits, images, code, etc.) to this
+repository, you confirm that:
 
   - You are the author of the content, OR you have explicit permission
     from the copyright holder to submit it
   - You retain copyright on your contribution
-  - You grant mlsystems.dev a non-exclusive, perpetual, worldwide license
-    to publish, display, and distribute your contribution on the site
-    and associated channels (RSS, newsletter, social media previews)
+  - You grant a non-exclusive, perpetual, worldwide license to publish,
+    display, and distribute your contribution on the site and associated
+    channels (RSS, newsletter, social media previews)
   - You may republish your own contribution elsewhere — you own it
diff --git a/README.md b/README.md
@@ -42,18 +42,6 @@ All contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md
 
 ---
 
-## Documentation
-
-| Doc                                                  | What it covers                                                     |
-| ---------------------------------------------------- | ------------------------------------------------------------------ |
-| [docs/writing-articles.md](docs/writing-articles.md) | How to write a post — frontmatter, MDX components, examples        |
-| [docs/architecture.md](docs/architecture.md)         | Project structure, design principles, why files are where they are |
-| [docs/deployment.md](docs/deployment.md)             | Deploying to Vercel, Cloudflare Pages, Netlify, or any static host |
-| [docs/seo.md](docs/seo.md)                           | What SEO is already wired in + pre-launch checklist                |
-| [docs/extending.md](docs/extending.md)               | Growing the site — auth, courses, comments, search, newsletter     |
-
----
-
 ## Tech stack
 
 [Astro 5](https://astro.build) · [MDX](https://mdxjs.com) · [React 19](https://react.dev) (islands only) · [Shiki](https://shiki.style) · TypeScript strict mode · plain CSS with custom properties
@@ -62,14 +50,13 @@ All contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md
 
 ## License
 
-- **Code** — [MIT](LICENSE). Fork freely, send PRs, build your own thing with it.
-- **Content** (blog posts, learning materials, diagrams) — © each author. All rights reserved.
+Everything here (blog posts, learning materials, diagrams, images, code) is © its respective author. All rights reserved.
 
 **You're welcome to:** read, link to, share URLs, cite posts in your own work, include brief excerpts in slides or presentations with attribution, and translate full posts into other languages (with credit + link back).
 
-**You need permission to:** republish full posts on other sites, use content in commercial products or paid courses, or create derivative works beyond translation. See [LICENSE](LICENSE) for the full terms.
+**You need permission to:** republish full posts on other sites, use content in commercial products or paid courses, or create derivative works beyond translation. Ask the respective author. See [LICENSE](LICENSE) for the full terms.
 
-Community contributors retain copyright on their own posts.
+Contributors retain copyright on their own work.
 
 ---
 

diff --git a/astro.config.mjs b/astro.config.mjs
@@ -43,7 +43,7 @@ try {
 }
 
 /** @type {string[]} */
-const SKIP_PATTERNS = [];
+const SKIP_PATTERNS = ['/write'];
 
 /**
  * @param {string} path
@@ -71,6 +71,9 @@ function changefreqFor(path) {
 export default defineConfig({
   site: 'https://mlsystems.dev',
   trailingSlash: 'ignore',
+  markdown: {
+    shikiConfig: { theme: 'github-dark' },
+  },
   integrations: [
     react(),
     mdx({
@@ -161,11 +164,23 @@ export default defineConfig({
   },
 
   vite: {
+    resolve: {
+      dedupe: ['react', 'react-dom'],
+    },
     ssr: {
       external: ['@resvg/resvg-js', 'satori'],
     },
     optimizeDeps: {
       exclude: ['@resvg/resvg-js', 'satori'],
+      include: [
+        'react',
+        'react-dom',
+        'react/jsx-runtime',
+        '@blocknote/core',
+        '@blocknote/react',
+        '@blocknote/mantine',
+        '@blocknote/code-block',
+      ],
     },
     build: {
       rollupOptions: {

diff --git a/docs/writing-articles.md b/docs/writing-articles.md
@@ -2,6 +2,8 @@
 
 Posts on **mlsystems.dev** live in `src/content/posts/`. Each post is a folder containing an `index.mdx` plus any images, components, or data that belong with it.
 
+> **Prefer not to write MDX by hand?** Visit [/write](https://mlsystems.dev/write) — a visual editor that produces a ready-to-publish post folder you can download and drop straight into `src/content/posts/`. No Markdown or setup required. The rest of this guide describes the folder that portal generates, for authors who want to write it directly.
+
 > Looking for the contribution _process_ (forking, branching, PR review)? See [CONTRIBUTING.md](../CONTRIBUTING.md). Adding yourself as an author? See [becoming-an-author.md](./becoming-an-author.md).
 
 ---
@@ -163,7 +165,15 @@ Every image needs **alt text** — the build warns if it's missing.
 
 ### Math
 
-LaTeX inside `$...$` (inline) or `$$...$$` (block). KaTeX rendering can be enabled — open an issue if you need it.
+KaTeX rendering is enabled. Write LaTeX inside `$...$` for inline math or `$$...$$` on its own lines for display equations:
+
+```mdx
+The attention scale factor is $1/\sqrt{d_k}$.
+
+$$
+\text{Attention}(Q, K, V) = \text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V
+$$
+```
 
 ---
 
@@ -295,17 +305,20 @@ Color is not part of Markdown, but because this is MDX you can drop in a span wh
 | <span style="color: var(--accent)">Warning</span> | ... |
 ```
 
-**Table designs.** Wrap a table in `<Table>` to change its look. Omit `variant` for the site default.
+**Table designs.** Wrap a table in `<Table>` to change its look. There are two independent controls: the **border style** (`variant`) and **zebra shading** (`zebra`), which can be combined.
+
+`variant` — the border style (pick one; omit for the default):
 
 | variant          | look                                       |
 | ---------------- | ------------------------------------------ |
 | `rule` (default) | header underline + hairline row separators |
-| `zebra`          | shaded alternating rows                    |
 | `lined`          | full grid, every cell bordered             |
 | `plain`          | header underline only, no row lines        |
 
+`zebra` — a boolean that shades alternating rows. It stacks on top of any border style, so `<Table variant="lined" zebra>` gives you a full grid _and_ shaded rows.
+
 ```mdx
-<Table variant="zebra">
+<Table variant="lined" zebra>
 
 | Model | Params         | VRAM (FP16) |
 | ----- | -------------- | ----------- |