From 346b7ad723c034f7696723f4846203d47ef86951 Mon Sep 17 00:00:00 2001
From: Michael Booth <michael@databooth.com.au>
Date: Sat, 30 May 2026 18:13:42 +1000
Subject: [PATCH 01/10] Update migration blog with cross-repo findings

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 docs/MOJO_1_0_MIGRATION_BLOG.md | 177 +++++++++++++++++++-------------
 1 file changed, 103 insertions(+), 74 deletions(-)

diff --git a/docs/MOJO_1_0_MIGRATION_BLOG.md b/docs/MOJO_1_0_MIGRATION_BLOG.md
index 121c292..132d3dd 100644
--- a/docs/MOJO_1_0_MIGRATION_BLOG.md
+++ b/docs/MOJO_1_0_MIGRATION_BLOG.md
@@ -1,79 +1,108 @@
-# mojo-toml migration notes: moving towards Mojo 1.0.0b1
-This post captures the first migration tranche for `mojo-toml`: aligning packaging/tooling and modernising standard-library imports so the repository is easier to keep compatible on the 1.0 beta line.
-
-## Why this migration was started
-The project had started moving to a 1.0-era toolchain, but some repository flows were still mixed between old and new conventions. The main risks were:
-- hidden CI/local breakage due to inconsistent recipe path assumptions,
-- ongoing migration friction across sibling `mojo-*` repositories,
-- stale docs and hooks teaching contributors the wrong command flow.
-
-## What was changed in this tranche
-### 1) Canonical recipe path and flow
-We standardised on `packaging/recipe.yaml` as the single recipe source and aligned the operational paths around it:
-- `pixi.toml` task `validate-recipe`,
-- `scripts/validate-recipe.sh`,
-- `scripts/build-recipe.sh`,
-- `scripts/pre_submit_checklist.py`,
-- `.github/workflows/pre-submit-validation.yml`,
-- `.github/workflows/validate-recipe.yml`,
-- `.pre-commit-config.yaml`,
-- docs that describe validation and pre-submit.
-
-### 2) Mojo stdlib import modernisation
-We migrated maintained `.mojo` files from legacy imports to `std.*` paths:
-- `from collections import ...` → `from std.collections import ...`
-- `from pathlib import Path` → `from std.pathlib import Path`
-
-Applied across core modules, key tests, examples, benchmarks, and dev helper tests.
-
-### 3) Documentation alignment
-We updated migration-sensitive docs to reflect the current packaging layout and toolchain assumptions, reducing copy/paste drift for future repos.
-
-## Pitfalls encountered (and how to avoid them)
-1. **Path drift between scripts and workflows**
-   Scripts were not always using the same recipe location as workflows. Fix by setting one canonical recipe path and threading it through every entry point.
-2. **Package installation assertions can silently rot**
-   One workflow checked the wrong install directory shape for this package. Keep install assertions based on actual package layout (`lib/mojo/toml` here), not package name guesswork.
-3. **Docs can lag after operational refactors**
-   Validation docs and quick-start snippets often become stale first. Treat docs updates as required in the same PR as tooling changes.
-
-## Repeatable checklist for other repositories
-Use this for:
+# mojo-* migration notes: what we learned moving to Mojo 1.0.0b1
+This write-up captures the full multi-repo migration wave across the DataBooth `mojo-*` libraries. The goal was practical: get everything onto a stable Mojo 1.0 beta workflow without breaking day-to-day development speed.
+
+## Why this wave mattered
+We were carrying a mix of old and new assumptions across repositories:
+- recipe validation paths diverged between local scripts, CI, and pre-commit,
+- several packages still depended on legacy import/syntax patterns,
+- test harnesses worked in one repo and failed in another for avoidable reasons,
+- and docs were increasingly out of sync with real commands.
+
+In short, this was operational debt, not just code debt.
+
+## What we standardised across repositories
+## 1) Packaging path consistency
+For packaging-focused repos, we standardised on `packaging/recipe.yaml` and pushed that path through:
+- `pixi.toml` tasks,
+- build/validation scripts,
+- pre-submit checklists,
+- pre-commit hooks,
+- workflow triggers,
+- and docs.
+
+Repos where this was applied in this tranche:
+- `mojo-toml`
+- `mojo-ini`
+- `mojo-yaml`
+- `mojo-dotenv`
+- `mojo-asciichart`
+
+## 2) Mojo 1.0 compatibility fixes
+The recurring upgrade pattern was:
+- move legacy imports to `std.*` where needed,
+- remove or replace APIs removed in 1.0 beta,
+- align tests with checked-raises semantics (`raises` where assertion helpers may raise),
+- and tighten task definitions so local validation matches real usage.
+
+## 3) Validation discipline
+Every repo was migrated with repo-native validation, not assumptions. Typical command sets included:
+- `pixi run test-all` (or equivalent),
+- targeted benchmark/example smoke runs where tests are limited,
+- `pixi run validate-recipe` for packaging repos,
+- and Python syntax checks where checklist scripts changed.
+
+## Repo-by-repo findings
+## mojo-ini / mojo-yaml / mojo-dotenv / mojo-asciichart
+These four were the cleanest high-leverage wins:
+- recipe-path drift resolved end-to-end,
+- pre-submit scripts aligned,
+- docs updated in the same change set,
+- validations passed with only non-blocking pixi/lock-format warnings.
+
+The important lesson: fixing operational path drift early removes most migration friction.
+
+## mojo-benchsuite
+Primary issue was framework-level Mojo compatibility in benchmark plumbing:
+- modernised collection imports,
+- removed brittle Python subprocess pattern used for version probing,
+- confirmed benchmark tasks (`run-example`, `bench-adaptive`, `bench-comprehensive`) still execute.
+
+This repo highlighted that benchmark frameworks are often more API-sensitive than the benchmark kernels themselves.
+
+## mojo-data-star
+This was the sharpest 1.0 API delta in the wave:
+- old tensor/layout + PythonObject conversion paths no longer compiled cleanly,
+- migrated to a simpler `MandelbrotGrid` representation for native Mojo tests,
+- updated checked-raises usage in Mojo tests,
+- rebased pixi constraints to the MAX 26.x line.
+
+Key takeaway: where interop APIs are still moving, simpler data models reduce upgrade risk substantially.
+
+## mojo-fireplace
+This repo needed a pragmatic test-flow stabilisation rather than full code modernisation:
+- ensured Mojo CLI availability in pixi env via MAX channel/dependency,
+- migrated Mojo test files to `std.testing` + checked-raises signatures,
+- fixed AoC string parsing that relied on deprecated slicing behaviour,
+- removed obsolete `Stringable` trait usage in Game of Life `gridv1`,
+- fixed Python interop test collection by setting `PYTHONPATH` in task execution.
+
+Outcome: the consolidated `pixi run test` path now passes on the migrated branch for the covered matrix.
+
+## The patterns that repeatedly bit us
+1. **Checked raises in tests**
+   Assertion helpers can raise; test functions and `main()` often need `raises` now.
+2. **String and conversion API drift**
+   Legacy convenience idioms (for example old slicing/conversion shortcuts) are now stricter.
+3. **Tooling path drift beats code drift**
+   More breakage came from scripts/hooks/workflows disagreeing than from core algorithms.
+4. **Interop wrappers age faster than core logic**
+   The pure compute kernels were usually fine; wrapper layers were where most compile churn appeared.
+
+## Practical migration playbook (kept short)
+1. Branch: `feature/mojo-1.0b1-migration`
+2. Fix packaging/tooling path consistency first.
+3. Run tests, then fix compile/runtime issues in clusters.
+4. Update docs in the same commit range.
+5. Re-run full validation commands before push.
+
+## Current status
+Migration commits are pushed on `feature/mojo-1.0b1-migration` for:
+- `mojo-ini`
+- `mojo-yaml`
+- `mojo-dotenv`
 - `mojo-asciichart`
 - `mojo-benchsuite`
 - `mojo-data-star`
-- `mojo-dotenv`
 - `mojo-fireplace`
-- `mojo-ini`
-- `mojo-yaml`
 
-1. **Create a migration branch**
-   - `git checkout -b feature/mojo-1.0b1-migration`
-2. **Pick one canonical recipe path**
-   - Prefer `packaging/recipe.yaml` (or explicitly decide otherwise), then update all scripts/workflows/hooks/docs to match.
-3. **Update Mojo import paths in `.mojo` files**
-   - Migrate `collections`/`pathlib` imports to `std.collections`/`std.pathlib` as applicable.
-4. **Run baseline validation**
-   - `pixi run mojo-version`
-   - `pixi run test-all`
-   - `pixi run examples-all` (if present)
-   - `pixi run validate-recipe`
-   - `pixi run pre-submit -- --skip-modular-community` (or project equivalent)
-5. **Fix failures by cluster**
-   - Tooling path issues first, then import/syntax issues, then behavioural regressions.
-6. **Update docs in same change set**
-   - Any file containing migration-sensitive commands should be updated before merge.
-7. **Capture repo-specific deltas**
-   - Record exceptions (for example package install layout differences) so the next repo migration is faster.
-
-## Current status (post-tranche update)
-- Migration-to-beta validation for `mojo-toml` is complete and green.
-- Version progression metadata has been aligned to `0.9.1`.
-- `scripts/pre_submit_checklist.py` now supports both `context.version` and `package.version` recipe layouts.
-- Operational docs were synchronised in both `docs/*.md` and `docs/planning/*.md`, while preserving intentionally historical release artefacts.
-
-## Next tranche for mojo-toml
-The next tranche should focus on optional warning-reduction and syntax modernisation polish (`fn`→`def` where required by target compiler behaviour), then re-run the full validation flow and fold findings back into this playbook.
-
-## Next execution focus across sibling repos
-The migration queue starts with repos that are closest to the completed `mojo-toml` pattern (`mojo-ini`, `mojo-yaml`, `mojo-dotenv`, `mojo-asciichart`) before moving to higher-variance repos (`mojo-benchsuite`, `mojo-data-star`, `mojo-fireplace`).
+Alongside the earlier `mojo-toml` completion work, this closes the current in-scope migration wave.

From 27fb15d77108cf03bd564748233e09b37d0c3a51 Mon Sep 17 00:00:00 2001
From: Michael Booth <michael@databooth.com.au>
Date: Sat, 30 May 2026 18:55:52 +1000
Subject: [PATCH 02/10] Document 0.9.1 distribution policy for beta releases

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 docs/MOJO_1_0_MIGRATION_BLOG.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/MOJO_1_0_MIGRATION_BLOG.md b/docs/MOJO_1_0_MIGRATION_BLOG.md
index 132d3dd..691868e 100644
--- a/docs/MOJO_1_0_MIGRATION_BLOG.md
+++ b/docs/MOJO_1_0_MIGRATION_BLOG.md
@@ -94,6 +94,33 @@ Outcome: the consolidated `pixi run test` path now passes on the migrated branch
 3. Run tests, then fix compile/runtime issues in clusters.
 4. Update docs in the same commit range.
 5. Re-run full validation commands before push.
+## Distribution policy for the 1.0 beta line
+To avoid users accidentally resolving to older modular-community builds, we are treating the DataBooth `0.9.1` line as the canonical Mojo 1.0 beta release stream.
+
+Pragmatic rule for now:
+- prefer DataBooth-hosted `0.9.1` packages for the migrated `mojo-*` libraries,
+- pin versions to `>=0.9.1,<0.10`,
+- and do not rely on older modular-community artefacts for these packages.
+
+Example consumer setup:
+
+```toml
+[project]
+channels = [
+  "conda-forge",
+  "https://conda.modular.com/max",
+  "<DATABOOTH_CHANNEL_URL>"
+]
+
+[dependencies]
+mojo-toml = ">=0.9.1,<0.10"
+mojo-ini = ">=0.9.1,<0.10"
+mojo-yaml = ">=0.9.1,<0.10"
+mojo-dotenv = ">=0.9.1,<0.10"
+mojo-asciichart = ">=0.9.1,<0.10"
+```
+
+If modular-community remains in a project for other packages, keep explicit version pins for these DataBooth libraries so old 26.x-era builds are not selected.
 
 ## Current status
 Migration commits are pushed on `feature/mojo-1.0b1-migration` for:

From 710f47dd26d7f8c18988951175b6a8a697af530e Mon Sep 17 00:00:00 2001
From: Michael Booth <michael@databooth.com.au>
Date: Sat, 30 May 2026 19:28:04 +1000
Subject: [PATCH 03/10] docs: align migration migration blog voice

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 docs/MOJO_1_0_MIGRATION_BLOG.md | 213 ++++++++++++++------------------
 1 file changed, 96 insertions(+), 117 deletions(-)

diff --git a/docs/MOJO_1_0_MIGRATION_BLOG.md b/docs/MOJO_1_0_MIGRATION_BLOG.md
index 691868e..6c08419 100644
--- a/docs/MOJO_1_0_MIGRATION_BLOG.md
+++ b/docs/MOJO_1_0_MIGRATION_BLOG.md
@@ -1,108 +1,99 @@
-# mojo-* migration notes: what we learned moving to Mojo 1.0.0b1
-This write-up captures the full multi-repo migration wave across the DataBooth `mojo-*` libraries. The goal was practical: get everything onto a stable Mojo 1.0 beta workflow without breaking day-to-day development speed.
-
-## Why this wave mattered
-We were carrying a mix of old and new assumptions across repositories:
-- recipe validation paths diverged between local scripts, CI, and pre-commit,
-- several packages still depended on legacy import/syntax patterns,
-- test harnesses worked in one repo and failed in another for avoidable reasons,
-- and docs were increasingly out of sync with real commands.
-
-In short, this was operational debt, not just code debt.
-
-## What we standardised across repositories
-## 1) Packaging path consistency
-For packaging-focused repos, we standardised on `packaging/recipe.yaml` and pushed that path through:
-- `pixi.toml` tasks,
-- build/validation scripts,
-- pre-submit checklists,
-- pre-commit hooks,
-- workflow triggers,
-- and docs.
-
-Repos where this was applied in this tranche:
+# Mojo 1.0 beta migration wave: what changed, what worked, and what’s next
+## Exec summary
+Over this migration wave, I moved the in-scope DataBooth `mojo-*` libraries onto one consistent Mojo 1.0 beta baseline.
+
+The goal was practical: reduce release friction, keep each package usable, and stop the “works in repo A, breaks in repo B” cycle.
+
+The result is a cleaner operational path, better cross-repo consistency, and one shared `0.9.1` beta line with matching tags.
+
+This post keeps the main story concise. Full technical notes are in the appendices.
+
+## Why this migration now
+The ecosystem has been moving quickly, and the repos had drifted in small but painful ways: packaging paths, validation assumptions, and compatibility handling.
+
+None of those issues was huge on its own. Together, they created avoidable drag in day-to-day delivery.
+
+So the migration focused on three things:
+- one release approach across repos,
+- one repeatable validation posture,
+- and one version line for this beta phase.
+
+## What was delivered
+### 1) Operational consistency
+For package-oriented repos, recipe handling and validation flow were aligned so local scripts, CI, and docs all reference the same source of truth.
+
+### 2) Compatibility uplift
+The key Mojo 1.0 beta breakpoints were addressed, including stricter API surfaces and checked-raises related test stabilisation.
+
+### 3) Release alignment
+All migrated repos now sit on a shared `0.9.1` beta line with corresponding tags, so consumers can target a coherent set of builds.
+
+## Alignment with agentic engineering practice
+This migration broadly followed the pattern in Modular’s write-up on building Mojo projects with AI agents:
+- human-led architecture and product judgement,
+- agent-led execution for repetitive, cross-repo, and boilerplate-heavy work.
+
+Where I deliberately diverged: distribution policy. Because packaging is still evolving, the practical choice for now is controlled `0.9.1` beta releases with explicit consumer pinning.
+
+Reference:
+- https://www.modular.com/blog/how-i-built-a-pure-mojo-app-and-10-libraries-with-ai-agents
+
+## Distribution stance for this beta phase
+For these migrated DataBooth libraries, the recommendation is to consume the `0.9.1` beta line and avoid fallback to older 26.x-era community artefacts.
+
+In practice:
+- prefer DataBooth-hosted packages for these libraries,
+- pin versions explicitly (`==0.9.1` is the safest default),
+- use modular-community for other dependencies only where needed.
+
+## Current status
+This closes the current in-scope migration wave across:
 - `mojo-toml`
 - `mojo-ini`
 - `mojo-yaml`
 - `mojo-dotenv`
 - `mojo-asciichart`
+- `mojo-benchsuite`
+- `mojo-data-star`
+- `mojo-fireplace`
 
-## 2) Mojo 1.0 compatibility fixes
-The recurring upgrade pattern was:
-- move legacy imports to `std.*` where needed,
-- remove or replace APIs removed in 1.0 beta,
-- align tests with checked-raises semantics (`raises` where assertion helpers may raise),
-- and tighten task definitions so local validation matches real usage.
-
-## 3) Validation discipline
-Every repo was migrated with repo-native validation, not assumptions. Typical command sets included:
-- `pixi run test-all` (or equivalent),
-- targeted benchmark/example smoke runs where tests are limited,
-- `pixi run validate-recipe` for packaging repos,
-- and Python syntax checks where checklist scripts changed.
-
-## Repo-by-repo findings
-## mojo-ini / mojo-yaml / mojo-dotenv / mojo-asciichart
-These four were the cleanest high-leverage wins:
-- recipe-path drift resolved end-to-end,
-- pre-submit scripts aligned,
-- docs updated in the same change set,
-- validations passed with only non-blocking pixi/lock-format warnings.
-
-The important lesson: fixing operational path drift early removes most migration friction.
-
-## mojo-benchsuite
-Primary issue was framework-level Mojo compatibility in benchmark plumbing:
-- modernised collection imports,
-- removed brittle Python subprocess pattern used for version probing,
-- confirmed benchmark tasks (`run-example`, `bench-adaptive`, `bench-comprehensive`) still execute.
-
-This repo highlighted that benchmark frameworks are often more API-sensitive than the benchmark kernels themselves.
-
-## mojo-data-star
-This was the sharpest 1.0 API delta in the wave:
-- old tensor/layout + PythonObject conversion paths no longer compiled cleanly,
-- migrated to a simpler `MandelbrotGrid` representation for native Mojo tests,
-- updated checked-raises usage in Mojo tests,
-- rebased pixi constraints to the MAX 26.x line.
-
-Key takeaway: where interop APIs are still moving, simpler data models reduce upgrade risk substantially.
-
-## mojo-fireplace
-This repo needed a pragmatic test-flow stabilisation rather than full code modernisation:
-- ensured Mojo CLI availability in pixi env via MAX channel/dependency,
-- migrated Mojo test files to `std.testing` + checked-raises signatures,
-- fixed AoC string parsing that relied on deprecated slicing behaviour,
-- removed obsolete `Stringable` trait usage in Game of Life `gridv1`,
-- fixed Python interop test collection by setting `PYTHONPATH` in task execution.
-
-Outcome: the consolidated `pixi run test` path now passes on the migrated branch for the covered matrix.
-
-## The patterns that repeatedly bit us
-1. **Checked raises in tests**
-   Assertion helpers can raise; test functions and `main()` often need `raises` now.
-2. **String and conversion API drift**
-   Legacy convenience idioms (for example old slicing/conversion shortcuts) are now stricter.
-3. **Tooling path drift beats code drift**
-   More breakage came from scripts/hooks/workflows disagreeing than from core algorithms.
-4. **Interop wrappers age faster than core logic**
-   The pure compute kernels were usually fine; wrapper layers were where most compile churn appeared.
-
-## Practical migration playbook (kept short)
-1. Branch: `feature/mojo-1.0b1-migration`
-2. Fix packaging/tooling path consistency first.
-3. Run tests, then fix compile/runtime issues in clusters.
-4. Update docs in the same commit range.
-5. Re-run full validation commands before push.
-## Distribution policy for the 1.0 beta line
-To avoid users accidentally resolving to older modular-community builds, we are treating the DataBooth `0.9.1` line as the canonical Mojo 1.0 beta release stream.
-
-Pragmatic rule for now:
-- prefer DataBooth-hosted `0.9.1` packages for the migrated `mojo-*` libraries,
-- pin versions to `>=0.9.1,<0.10`,
-- and do not rely on older modular-community artefacts for these packages.
-
-Example consumer setup:
+## What happens next
+Near term, the plan stays simple and low-risk:
+- keep the `0.9.1` beta line clean,
+- keep release mechanics repeatable,
+- revisit packaging strategy once the ecosystem settles further.
+
+## Appendix A: Repo-level technical notes
+### `mojo-ini`, `mojo-yaml`, `mojo-dotenv`, `mojo-asciichart`
+- Consolidated recipe-path handling and pre-submit flow.
+- Synced migration-sensitive docs with the operational command path.
+- Retained passing validation with only non-blocking tool warnings.
+
+### `mojo-benchsuite`
+- Updated compatibility in benchmark plumbing.
+- Removed brittle subprocess-based version probing.
+- Confirmed benchmark task execution after migration.
+
+### `mojo-data-star`
+- Reworked the most brittle 1.0 beta interop surface.
+- Simplified data-shape handling to reduce API churn exposure.
+- Brought Mojo/Python test paths back into a stable green state.
+
+### `mojo-fireplace`
+- Stabilised Mojo test flow and environment assumptions.
+- Updated test patterns for checked raises and current stdlib usage.
+- Fixed practical runtime and test-path issues that blocked reliable local validation.
+
+## Appendix B: Practical migration sequence used
+1. Create or switch to `feature/mojo-1.0b1-migration`.
+2. Resolve packaging and tooling path consistency first.
+3. Run repo-native tests and validation.
+4. Fix compiler and runtime issues in clusters.
+5. Update docs in the same change set.
+6. Re-run full validation before push.
+
+## Appendix C: Consumer install policy example
+For projects consuming the DataBooth beta-line releases:
 
 ```toml
 [project]
@@ -113,23 +104,11 @@ channels = [
 ]
 
 [dependencies]
-mojo-toml = ">=0.9.1,<0.10"
-mojo-ini = ">=0.9.1,<0.10"
-mojo-yaml = ">=0.9.1,<0.10"
-mojo-dotenv = ">=0.9.1,<0.10"
-mojo-asciichart = ">=0.9.1,<0.10"
+mojo-toml = "==0.9.1"
+mojo-ini = "==0.9.1"
+mojo-yaml = "==0.9.1"
+mojo-dotenv = "==0.9.1"
+mojo-asciichart = "==0.9.1"
 ```
 
-If modular-community remains in a project for other packages, keep explicit version pins for these DataBooth libraries so old 26.x-era builds are not selected.
-
-## Current status
-Migration commits are pushed on `feature/mojo-1.0b1-migration` for:
-- `mojo-ini`
-- `mojo-yaml`
-- `mojo-dotenv`
-- `mojo-asciichart`
-- `mojo-benchsuite`
-- `mojo-data-star`
-- `mojo-fireplace`
-
-Alongside the earlier `mojo-toml` completion work, this closes the current in-scope migration wave.
+If modular-community is present for other packages, explicit pins prevent accidental resolution to older incompatible builds for these libraries.

From d28f89f5b3736f2f75b59cb1ad546fed301b4b39 Mon Sep 17 00:00:00 2001
From: Michael Booth <michael@databooth.com.au>
Date: Sat, 30 May 2026 20:09:37 +1000
Subject: [PATCH 04/10] docs/workflows: update migration release scope and pixi
 validation

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 .github/workflows/validate-recipe.yml |  2 +-
 docs/MOJO_1_0_MIGRATION_BLOG.md       | 77 +++++++++++++++++++++++----
 2 files changed, 69 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/validate-recipe.yml b/.github/workflows/validate-recipe.yml
index 1f1111f..7ceed4a 100644
--- a/.github/workflows/validate-recipe.yml
+++ b/.github/workflows/validate-recipe.yml
@@ -17,7 +17,7 @@ jobs:
 
       - uses: prefix-dev/setup-pixi@v0.9.3
         with:
-          pixi-version: v0.37.0
+          pixi-version: latest
 
       - name: Install rattler-build
         run: pixi global install rattler-build
diff --git a/docs/MOJO_1_0_MIGRATION_BLOG.md b/docs/MOJO_1_0_MIGRATION_BLOG.md
index 6c08419..d5460a0 100644
--- a/docs/MOJO_1_0_MIGRATION_BLOG.md
+++ b/docs/MOJO_1_0_MIGRATION_BLOG.md
@@ -1,10 +1,28 @@
++++
+title = "Mojo 1.0 beta migration wave: what changed, what worked, and what’s next"
+date = "2026-05-30"
+draft = false
+[taxonomies]
+tags = [
+  "Mojo 🔥",
+  "Mojo 1.0 Beta",
+  "Library Migration",
+  "Release Engineering",
+  "Open Source",
+  "Packaging",
+  "Testing",
+  "Refactoring"
+]
+[extra]
+comment = true
++++
 # Mojo 1.0 beta migration wave: what changed, what worked, and what’s next
 ## Exec summary
-Over this migration wave, I moved the in-scope DataBooth `mojo-*` libraries onto one consistent Mojo 1.0 beta baseline.
+Over this migration wave, I moved my `mojo-*` libraries onto one consistent Mojo 1.0 beta baseline.
 
 The goal was practical: reduce release friction, keep each package usable, and stop the “works in repo A, breaks in repo B” cycle.
 
-The result is a cleaner operational path, better cross-repo consistency, and one shared `0.9.1` beta line with matching tags.
+The result is a cleaner operational path, better cross-repo consistency, and a clear public release set on the `0.9.1` beta line.
 
 This post keeps the main story concise. Full technical notes are in the appendices.
 
@@ -46,20 +64,34 @@ In practice:
 - pin versions explicitly (`==0.9.1` is the safest default),
 - use modular-community for other dependencies only where needed.
 
-## Current status
-This closes the current in-scope migration wave across:
+## Public release scope for this wave
+This public release now focuses on five libraries:
 - `mojo-toml`
 - `mojo-ini`
 - `mojo-yaml`
 - `mojo-dotenv`
 - `mojo-asciichart`
-- `mojo-benchsuite`
+
+Deferred for follow-up releases:
+- `mojo-benchsuite` (I want to expand practical use cases and release guidance first)
 - `mojo-data-star`
 - `mojo-fireplace`
 
+## Current status
+This closes the current migration execution wave across:
+- `mojo-toml`
+- `mojo-ini`
+- `mojo-yaml`
+- `mojo-dotenv`
+- `mojo-asciichart`
+- `mojo-benchsuite` (deferred from this public release)
+- `mojo-data-star` (deferred from this public release)
+- `mojo-fireplace` (deferred from this public release)
+
 ## What happens next
 Near term, the plan stays simple and low-risk:
-- keep the `0.9.1` beta line clean,
+- publish and support the five-library `0.9.1` release cleanly,
+- expand `mojo-benchsuite` use-case content before its public release,
 - keep release mechanics repeatable,
 - revisit packaging strategy once the ecosystem settles further.
 
@@ -73,16 +105,19 @@ Near term, the plan stays simple and low-risk:
 - Updated compatibility in benchmark plumbing.
 - Removed brittle subprocess-based version probing.
 - Confirmed benchmark task execution after migration.
+- Public release deferred until richer practical use cases are documented.
 
 ### `mojo-data-star`
 - Reworked the most brittle 1.0 beta interop surface.
 - Simplified data-shape handling to reduce API churn exposure.
 - Brought Mojo/Python test paths back into a stable green state.
+- Public release deferred for now.
 
 ### `mojo-fireplace`
 - Stabilised Mojo test flow and environment assumptions.
 - Updated test patterns for checked raises and current stdlib usage.
 - Fixed practical runtime and test-path issues that blocked reliable local validation.
+- Public release deferred for now.
 
 ## Appendix B: Practical migration sequence used
 1. Create or switch to `feature/mojo-1.0b1-migration`.
@@ -92,15 +127,16 @@ Near term, the plan stays simple and low-risk:
 5. Update docs in the same change set.
 6. Re-run full validation before push.
 
-## Appendix C: Consumer install policy example
-For projects consuming the DataBooth beta-line releases:
+## Appendix C: Consumer install policy examples
+### Option 1: Packaged installs via a DataBooth channel (recommended)
+For packaged releases, use one package channel URL plus explicit pins:
 
 ```toml
 [project]
 channels = [
   "conda-forge",
   "https://conda.modular.com/max",
-  "<DATABOOTH_CHANNEL_URL>"
+  "<DATABOOTH_CONDA_CHANNEL_URL>"
 ]
 
 [dependencies]
@@ -111,4 +147,27 @@ mojo-dotenv = "==0.9.1"
 mojo-asciichart = "==0.9.1"
 ```
 
+Important: `<DATABOOTH_CONDA_CHANNEL_URL>` is the package index/channel endpoint, not individual GitHub repository URLs.
+
 If modular-community is present for other packages, explicit pins prevent accidental resolution to older incompatible builds for these libraries.
+
+### Option 2: Source consumption from GitHub repos (follow-up or experimental)
+If you want to consume directly from source, add each library repo and include its `src` path when running Mojo:
+
+```bash
+git submodule add https://github.com/databooth/mojo-toml vendor/mojo-toml
+git submodule add https://github.com/databooth/mojo-ini vendor/mojo-ini
+git submodule add https://github.com/databooth/mojo-yaml vendor/mojo-yaml
+git submodule add https://github.com/databooth/mojo-dotenv vendor/mojo-dotenv
+git submodule add https://github.com/databooth/mojo-asciichart vendor/mojo-asciichart
+```
+
+```bash
+mojo \
+  -I vendor/mojo-toml/src \
+  -I vendor/mojo-ini/src \
+  -I vendor/mojo-yaml/src \
+  -I vendor/mojo-dotenv/src \
+  -I vendor/mojo-asciichart/src \
+  your_app.mojo
+```

From 270b26983402348c41e58055b442b044d43d96bc Mon Sep 17 00:00:00 2001
From: Michael Booth <michael@databooth.com.au>
Date: Sat, 30 May 2026 22:01:44 +1000
Subject: [PATCH 05/10] docs: refine migration blog and add forum announcements

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 docs/FORUM_MODULAR_ANNOUNCEMENT_0_9_1.md      | 30 +++++++++++++++++++
 docs/FORUM_MODULAR_ANNOUNCEMENT_0_9_1_TLDR.md | 14 +++++++++
 docs/MOJO_1_0_MIGRATION_BLOG.md               | 12 --------
 3 files changed, 44 insertions(+), 12 deletions(-)
 create mode 100644 docs/FORUM_MODULAR_ANNOUNCEMENT_0_9_1.md
 create mode 100644 docs/FORUM_MODULAR_ANNOUNCEMENT_0_9_1_TLDR.md

diff --git a/docs/FORUM_MODULAR_ANNOUNCEMENT_0_9_1.md b/docs/FORUM_MODULAR_ANNOUNCEMENT_0_9_1.md
new file mode 100644
index 0000000..e0e8c92
--- /dev/null
+++ b/docs/FORUM_MODULAR_ANNOUNCEMENT_0_9_1.md
@@ -0,0 +1,30 @@
+# Mojo 1.0 beta migration complete for 5 DataBooth libraries (all prior versions now deprecated)
+
+Hi all — quick release update from my small `mojo-*` ecosystem.
+
+I’ve now completed the Mojo 1.0 beta migration for these five libraries, all aligned on **`0.9.1`**:
+
+- `mojo-toml`
+- `mojo-ini`
+- `mojo-yaml`
+- `mojo-dotenv`
+- `mojo-asciichart`
+
+## What this means
+
+- **`0.9.1` is now the supported baseline** for these five libraries.
+- **All earlier versions are now deprecated** for these libraries.
+- If you’re consuming them, please pin explicitly to `==0.9.1` for now.
+
+## Why this release matters
+
+The main goal was consistency and lower-friction maintenance across multiple repositories:
+
+- one migration line,
+- one compatible beta baseline,
+- one clearer support target.
+
+I’m hopeful this makes the final step from Mojo 1.0 beta to Mojo v1.0 smaller (or at least smaller than previous jumps).
+
+
+Thanks to the Modular team and community — this ecosystem is still small, but I’m continuing to invest in it and keep it aligned with current Mojo releases.
diff --git a/docs/FORUM_MODULAR_ANNOUNCEMENT_0_9_1_TLDR.md b/docs/FORUM_MODULAR_ANNOUNCEMENT_0_9_1_TLDR.md
new file mode 100644
index 0000000..864c3e9
--- /dev/null
+++ b/docs/FORUM_MODULAR_ANNOUNCEMENT_0_9_1_TLDR.md
@@ -0,0 +1,14 @@
+# TL;DR: Mojo 1.0 beta migration complete for 5 libraries (`0.9.1`)
+
+Quick update: I’ve completed Mojo 1.0 beta migration for five DataBooth libraries, all now aligned on **`0.9.1`**:
+
+- `mojo-toml`
+- `mojo-ini`
+- `mojo-yaml`
+- `mojo-dotenv`
+- `mojo-asciichart`
+
+For these five libraries, **all earlier versions are now deprecated**.  
+If you’re consuming them, please pin to **`==0.9.1`** for now.
+
+I’m aiming to make the final step from Mojo 1.0 beta to Mojo v1.0 a smaller transition than previous upgrades.
diff --git a/docs/MOJO_1_0_MIGRATION_BLOG.md b/docs/MOJO_1_0_MIGRATION_BLOG.md
index d5460a0..2f01f7c 100644
--- a/docs/MOJO_1_0_MIGRATION_BLOG.md
+++ b/docs/MOJO_1_0_MIGRATION_BLOG.md
@@ -72,11 +72,6 @@ This public release now focuses on five libraries:
 - `mojo-dotenv`
 - `mojo-asciichart`
 
-Deferred for follow-up releases:
-- `mojo-benchsuite` (I want to expand practical use cases and release guidance first)
-- `mojo-data-star`
-- `mojo-fireplace`
-
 ## Current status
 This closes the current migration execution wave across:
 - `mojo-toml`
@@ -84,14 +79,10 @@ This closes the current migration execution wave across:
 - `mojo-yaml`
 - `mojo-dotenv`
 - `mojo-asciichart`
-- `mojo-benchsuite` (deferred from this public release)
-- `mojo-data-star` (deferred from this public release)
-- `mojo-fireplace` (deferred from this public release)
 
 ## What happens next
 Near term, the plan stays simple and low-risk:
 - publish and support the five-library `0.9.1` release cleanly,
-- expand `mojo-benchsuite` use-case content before its public release,
 - keep release mechanics repeatable,
 - revisit packaging strategy once the ecosystem settles further.
 
@@ -105,19 +96,16 @@ Near term, the plan stays simple and low-risk:
 - Updated compatibility in benchmark plumbing.
 - Removed brittle subprocess-based version probing.
 - Confirmed benchmark task execution after migration.
-- Public release deferred until richer practical use cases are documented.
 
 ### `mojo-data-star`
 - Reworked the most brittle 1.0 beta interop surface.
 - Simplified data-shape handling to reduce API churn exposure.
 - Brought Mojo/Python test paths back into a stable green state.
-- Public release deferred for now.
 
 ### `mojo-fireplace`
 - Stabilised Mojo test flow and environment assumptions.
 - Updated test patterns for checked raises and current stdlib usage.
 - Fixed practical runtime and test-path issues that blocked reliable local validation.
-- Public release deferred for now.
 
 ## Appendix B: Practical migration sequence used
 1. Create or switch to `feature/mojo-1.0b1-migration`.

From 7b2762ab7576b77a3de4872109507addd5f6f877 Mon Sep 17 00:00:00 2001
From: Michael Booth <michael@databooth.com.au>
Date: Sat, 20 Jun 2026 22:59:24 +1000
Subject: [PATCH 06/10] Set up Great Docs publishing for GitHub Pages

- add Great Docs config and blog findings post
- add GitHub Actions docs workflow
- ignore generated Great Docs build artifacts

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 .github/workflows/docs.yml                   | 110 +++++++++++++++++++
 .gitignore                                   |   9 ++
 blog/2026-06-20-great-docs-mojo-findings.qmd |  47 ++++++++
 great-docs.yml                               |  20 ++++
 4 files changed, 186 insertions(+)
 create mode 100644 .github/workflows/docs.yml
 create mode 100644 blog/2026-06-20-great-docs-mojo-findings.qmd
 create mode 100644 great-docs.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..3116e1f
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,110 @@
+name: CI Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build-docs:
+    name: "Build Docs"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # Full history for accurate page timestamps
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install package and dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+          python -m pip install great-docs
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Build docs
+        run: great-docs build
+
+      - name: Save docs artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-html
+          path: great-docs/_site
+          include-hidden-files: true
+
+      - name: Upload build timings
+        uses: actions/upload-artifact@v7
+        with:
+          name: build-timings
+          path: great-docs/_site/build-timings.json
+
+  publish-docs:
+    name: "Publish Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: great-docs/_site
+          include-hidden-files: true
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
+
+  preview-docs:
+    name: "Preview Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.event_name == 'pull_request'
+    permissions:
+      deployments: write
+      pull-requests: write
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+      # Start deployment
+      - name: Configure pull release name
+        if: ${{ github.event_name == 'pull_request' }}
+        run: |
+          echo "RELEASE_NAME=pr-${{ github.event.number }}" >> $GITHUB_ENV
+
+      - name: Configure branch release name
+        if: ${{ github.event_name != 'pull_request' }}
+        run: |
+          # use branch name, but replace slashes. E.g. feat/a -> feat-a
+          echo "RELEASE_NAME=${GITHUB_REF_NAME//\//-}" >> $GITHUB_ENV
+
+      # Deploy
+      - name: Create Github Deployment
+        uses: bobheadxi/deployments@v1
+        id: deployment
+        if: ${{ !github.event.pull_request.head.repo.fork }}
+        with:
+          step: start
+          token: ${{ secrets.GITHUB_TOKEN }}
+          env: ${{ env.RELEASE_NAME }}
+          ref: ${{ github.head_ref }}
+          logs: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
diff --git a/.gitignore b/.gitignore
index db05e06..033ba31 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,3 +31,12 @@ Thumbs.db
 .pixi/
 pixi.lock
 output/
+
+# Great Docs build directory (ephemeral, do not commit)
+great-docs/
+
+# Great Docs versioned-build artifacts
+_great_docs_build/
+.great-docs-build/
+.great-docs-cache/
+.great-docs/
diff --git a/blog/2026-06-20-great-docs-mojo-findings.qmd b/blog/2026-06-20-great-docs-mojo-findings.qmd
new file mode 100644
index 0000000..3089280
--- /dev/null
+++ b/blog/2026-06-20-great-docs-mojo-findings.qmd
@@ -0,0 +1,47 @@
+---
+title: "Great Docs on a Mojo-first repository: early findings"
+date: 2026-06-20
+description: "Initial findings from trialling Great Docs in the mojo-toml project."
+---
+
+## What we tested
+- Ran `great-docs init` in a Mojo-first repository.
+- Reviewed generated configuration behaviour for non-Python package layout.
+- Prepared a first-pass `great-docs.yml` that prioritises narrative docs and blog content.
+- Ran `great-docs build` and `great-docs build --no-refresh` after configuration updates.
+
+## Early findings
+- Initialisation succeeds, but package auto-discovery cannot infer a Python API surface.
+- Great Docs is still useful for polished site generation around Markdown/QMD documentation.
+- A custom docs-first configuration works as a practical starting point for Mojo projects.
+
+## Build findings
+- Build completed successfully: `19/19` steps, with `10` skipped and `11` warnings.
+- Output site was generated at `great-docs/_site/index.html`.
+- User Guide processing picked up `31` pages from `docs/`.
+- Blog processing picked up this post from `blog/`.
+- The most common warnings were unresolved README relative links after content was re-rooted for rendering.
+- A skills-page warning indicated `site_url` is not yet configured in `great-docs.yml`.
+
+## Tooling migration: pre-commit to prek
+- Repository automation was migrated from `pre-commit` commands to `prek`.
+- `pixi.toml` now exposes `prek` and `prek-install` tasks.
+- Project dependency changed from `pre-commit` to `prek`.
+- Existing `.pre-commit-config.yaml` remains valid and is used by `prek`.
+- Supporting docs were updated so local quality checks consistently reference `prek`.
+
+## Warning details worth addressing
+- Unresolved links to:
+  - `README.md`
+  - `CHANGELOG.md`
+  - `docs/PLATFORM_BUILDS.md`
+  - `docs/planning/REFLECTION_SERIALIZATION.md`
+  - `docs/planning/ROADMAP.md`
+  - `docs/PERFORMANCE.md`
+- Missing site URL for generated skills metadata.
+
+## Next validation steps
+- Add `site_url` once docs hosting URL is finalised.
+- Normalise cross-links in `README.md` and docs pages for Quarto-rendered paths.
+- Decide whether to keep `docs/planning/` in published navigation.
+- Decide whether to add a manual API section for Mojo symbols.
diff --git a/great-docs.yml b/great-docs.yml
new file mode 100644
index 0000000..3b72f0f
--- /dev/null
+++ b/great-docs.yml
@@ -0,0 +1,20 @@
+display_name: mojo-toml
+repo: https://github.com/databooth/mojo-toml
+site_url: https://databooth.github.io/mojo-toml/
+github_style: widget
+pypi: false
+parser: numpy
+dynamic: false
+dark_mode_toggle: true
+
+source:
+  enabled: true
+  branch: main
+
+user_guide: docs
+
+sections:
+  - title: Blog
+    dir: blog
+    type: blog
+    navbar_after: Reference

From 3ac4f260a4a2fa0504dbb6ca277e26561bf15976 Mon Sep 17 00:00:00 2001
From: "Michael J. Booth" <michael@databooth.com.au>
Date: Sat, 20 Jun 2026 23:03:21 +1000
Subject: [PATCH 07/10] Potential fix for pull request finding 'CodeQL /
 Workflow does not contain permissions'

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
---
 .github/workflows/docs.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 3116e1f..b278c37 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -10,6 +10,8 @@ jobs:
   build-docs:
     name: "Build Docs"
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v6
         with:

From af9b74f9686d6144137d6f66ac163f40f7dc20fa Mon Sep 17 00:00:00 2001
From: Michael Booth <michael@databooth.com.au>
Date: Sat, 20 Jun 2026 23:10:04 +1000
Subject: [PATCH 08/10] Fix CI workflow command mismatches

- remove editable package install from docs build workflow
- run examples via examples-all task in test workflow
- update pre-submit pixi install flow for current CLI syntax

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 .github/workflows/docs.yml                  |  3 +--
 .github/workflows/pre-submit-validation.yml | 10 ++++++----
 .github/workflows/test.yml                  |  5 ++---
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index b278c37..7e17732 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -21,10 +21,9 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install package and dependencies
+      - name: Install docs dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e .
           python -m pip install great-docs
 
       - name: Set up Quarto
diff --git a/.github/workflows/pre-submit-validation.yml b/.github/workflows/pre-submit-validation.yml
index 60747cd..03859b7 100644
--- a/.github/workflows/pre-submit-validation.yml
+++ b/.github/workflows/pre-submit-validation.yml
@@ -77,13 +77,15 @@ jobs:
 
         pixi init "$TEST_PROJECT"
 
+        # Add channels to test project
+        pixi workspace channel add --manifest-path "$TEST_PROJECT/pixi.toml" "file://$(pwd)/output" --prepend
+        pixi workspace channel add --manifest-path "$TEST_PROJECT/pixi.toml" conda-forge
+        pixi workspace channel add --manifest-path "$TEST_PROJECT/pixi.toml" https://conda.modular.com/max
+        pixi workspace channel add --manifest-path "$TEST_PROJECT/pixi.toml" https://prefix.dev/modular-community
+
         # Add package from local build
         pixi add \
           --manifest-path "$TEST_PROJECT/pixi.toml" \
-          --channel "file://$(pwd)/output" \
-          --channel conda-forge \
-          --channel https://conda.modular.com/max \
-          --channel https://prefix.dev/modular-community \
           mojo-toml
 
         # Verify installation
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 5998074..d833359 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -30,9 +30,8 @@ jobs:
 
     - name: Run examples
       run: |
-        pixi run example-simple
-        pixi run example-pixi
+        pixi run examples-all
 
     - name: Test summary
       if: always()
-      run: echo "✅ All 79 tests passed"
+      run: echo "✅ Test workflow completed"

From 96201472a8aa3fb8fde70def39382d2889086bba Mon Sep 17 00:00:00 2001
From: Michael Booth <michael@databooth.com.au>
Date: Sat, 20 Jun 2026 23:17:50 +1000
Subject: [PATCH 09/10] Use uvx to run Great Docs in CI

- install uv in docs workflow
- run docs build with uvx great-docs

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 .github/workflows/docs.yml | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 7e17732..d1d6cef 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -21,16 +21,15 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install docs dependencies
+      - name: Install uv
         run: |
-          python -m pip install --upgrade pip
-          python -m pip install great-docs
+          python -m pip install --upgrade pip uv
 
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2
 
       - name: Build docs
-        run: great-docs build
+        run: uvx great-docs build
 
       - name: Save docs artifact
         uses: actions/upload-artifact@v7

From cc2e4f2159eb680857f8b6129492e5229c1696f1 Mon Sep 17 00:00:00 2001
From: Michael Booth <michael@databooth.com.au>
Date: Sat, 20 Jun 2026 23:40:52 +1000
Subject: [PATCH 10/10] Fix docs list rendering and publish llms text files

- add explicit markdown spacing for README bullet lists
- add static llms.txt and llms-full.txt content
- copy llms files into _site and .well-known during docs workflow

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 .github/workflows/docs.yml |  7 +++++++
 README.md                  |  7 +++++++
 llms-full.txt              | 21 +++++++++++++++++++++
 llms.txt                   | 11 +++++++++++
 4 files changed, 46 insertions(+)
 create mode 100644 llms-full.txt
 create mode 100644 llms.txt

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index d1d6cef..7e09023 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -31,6 +31,13 @@ jobs:
       - name: Build docs
         run: uvx great-docs build
 
+      - name: Add llms text files
+        run: |
+          cp llms.txt llms-full.txt great-docs/_site/
+          mkdir -p great-docs/_site/.well-known
+          cp llms.txt great-docs/_site/.well-known/llms.txt
+          cp llms-full.txt great-docs/_site/.well-known/llms-full.txt
+
       - name: Save docs artifact
         uses: actions/upload-artifact@v7
         with:
diff --git a/README.md b/README.md
index c723df3..e39c401 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@
 `mojo-toml` enables native TOML parsing in Mojo without Python dependencies. Parse configuration files, project settings, and structured data with a clean, type-safe API.
 
 **Key features:**
+
 - ✅ **TOML 1.0 compliant** - full specification support
 - ✅ **Array of tables** - `[[section]]` syntax for repeated table arrays
 - ✅ **Alternative number bases** - hex (`0xDEAD`), octal (`0o755`), binary (`0b1101`)
@@ -200,10 +201,12 @@ pixi add mojo-toml
 ### 🔮 TOML 1.1 (Partial Support)
 
 TOML 1.1 features implemented:
+
 - ✅ `\\xHH` escape sequences for codepoints 0-255 (e.g., `\\x00`, `\\x61`)
 - ✅ `\\e` escape for escape character (U+001B)
 
 TOML 1.1 features not yet implemented:
+
 - Multiline inline tables with trailing commas
 - Optional seconds in datetime/time values
 
@@ -264,6 +267,7 @@ pixi run benchmark-python
 ```
 
 Both benchmarks generate markdown reports in `benchmarks/reports/` with:
+
 - System specifications (OS, CPU, GPU, RAM, Mojo/Python versions)
 - Performance tables with throughput and latency
 - Timestamp and machine configuration
@@ -292,15 +296,18 @@ See [ROADMAP.md](docs/planning/ROADMAP.md) for areas where contributions would b
 ## Related Projects
 
 **Other Mojo Config Libraries:**
+
 - **[mojo-ini](https://github.com/databooth/mojo-ini)** - INI file parser with Python configparser compatibility
 - **[mojo-dotenv](https://github.com/databooth/mojo-dotenv)** - Load environment variables from .env files
 
 **Other TOML Parsers in Mojo:**
+
 - **[decimojo/tomlmojo](https://github.com/forfudan/decimojo/tree/main/src/tomlmojo)** - Lightweight TOML parser (~900 LOC, parser-only) embedded in the decimojo library. Good choice if you only need basic config reading for tests and don't need a standalone package or TOML 1.0 features.
 
 ## Acknowledgements
 
 Special thanks to:
+
 - **[DataBooth](https://www.databooth.com.au/posts/mojo)** - Project sponsor, building high-performance data and AI services with Mojo
 - **[Python tomli](https://github.com/hukkin/tomli)** - Reference implementation for validation
 - **[TOML Specification](https://toml.io/en/v1.0.0)** - Tom Preston-Werner's excellent config format
diff --git a/llms-full.txt b/llms-full.txt
new file mode 100644
index 0000000..98ddfc0
--- /dev/null
+++ b/llms-full.txt
@@ -0,0 +1,21 @@
+# mojo-toml
+> Native TOML 1.0 parser and writer for Mojo with zero Python runtime dependencies.
+## Project Summary
+mojo-toml provides parsing and writing support for TOML configuration files in Mojo.
+The library targets TOML 1.0 compliance and includes partial TOML 1.1 support.
+## Core Features
+- TOML 1.0 parser support, including nested tables, dotted keys, arrays, and inline tables.
+- TOML writer support with semantic round-trip fidelity.
+- Validation for duplicates and malformed structures with line and column error context.
+- Support for additional numeric bases (`0x`, `0o`, `0b`) and selected TOML 1.1 escapes.
+## Primary Docs
+- Home: https://databooth.github.io/mojo-toml/
+- Changelog: https://databooth.github.io/mojo-toml/changelog.html
+- Performance: https://databooth.github.io/mojo-toml/user-guide/PERFORMANCE.html
+- Platform builds: https://databooth.github.io/mojo-toml/user-guide/PLATFORM_BUILDS.html
+- Roadmap: https://databooth.github.io/mojo-toml/roadmap.html
+## Install Guidance
+- Recommended packaging and release consumption is documented in the home page and user guide pages.
+- For source-based consumption, use the repository and include `src` in Mojo include paths.
+## Repository
+- GitHub: https://github.com/DataBooth/mojo-toml
diff --git a/llms.txt b/llms.txt
new file mode 100644
index 0000000..cb9de95
--- /dev/null
+++ b/llms.txt
@@ -0,0 +1,11 @@
+# mojo-toml
+> Native TOML 1.0 parser and writer for Mojo with zero Python runtime dependencies.
+## Documentation
+- [Home](https://databooth.github.io/mojo-toml/): Project overview, quickstart, installation, and usage.
+- [Changelog](https://databooth.github.io/mojo-toml/changelog.html): Release history and version notes.
+- [Performance](https://databooth.github.io/mojo-toml/user-guide/PERFORMANCE.html): Benchmark methodology and results.
+- [Platform Builds](https://databooth.github.io/mojo-toml/user-guide/PLATFORM_BUILDS.html): Packaging and platform build considerations.
+- [Roadmap](https://databooth.github.io/mojo-toml/roadmap.html): Planned improvements and future work.
+- [Blog Findings](https://databooth.github.io/mojo-toml/blog/2026-06-20-great-docs-mojo-findings.html): Great Docs rollout findings for this repository.
+## Source
+- [Repository](https://github.com/DataBooth/mojo-toml)