Documentation Roadmap

We are still building these docs. This is not a closed checklist with a finish line. Install → book → core stdlib is a baseline you can use today; everything else is active expansion — more recipes, more depth, more surfaces over time.

This page is the public progress tracker for AlefDocs. Private language/runtime source stays private. Metrics here are docs-only.

Live: mturac.github.io/alefdocs · Repo: github.com/mturac/alefdocs

Updated: 2026-07-18 · Mode: expand · polish · ship next slice

How to read this

There is no “docs v1 done, stop.” A live baseline means strangers can learn and run programs. Expansion means we keep adding pages, recipes, and depth.

Where we are going (read this first)

BASELINE (usable today)       EXPANSION (what we keep building)
[████████████] install, book,   [██░░░░░░░░░░░░░░░░░░░░] agent path,
               core stdlib,                   recipes, API index,
               July 2026 notes                locales, more apps…

Expansion is the product of this roadmap. Expect the right-hand bar to move for a long time — that is intentional.

Building now

Start here while we expand:

• AI Agent Backend · Building
• Jobs · Live · more recipes coming
• What's New — July 2026 · snapshot, not a freeze

At a glance

Expansion — still building

Phase 6 — Agent backend path · Building

Goal: one copy-pasteable public recipe — chat API + history + stub AI + shutdown — from docs alone.

Phase 7 — Cookbook expansion · Building / Queued

Recipes we intend to grow into full pages (ordered by usefulness, not vapor):

• Provider-gated live AI (stub stays default for CI)
• Rate limit + auth middleware sketches
• SQLite migrations for chat sessions
• alef.mod small-library / vendor sketch
• Webhook + job retry patterns
• Health, metrics, graceful shutdown checklist

Phase 8 — Spec and navigation · Queued

• Close language-spec vs book gaps
• Every SUMMARY entry has a working pages/*.html twin
• Stronger “Start → Tour → Stdlib → Roadmap” path on the home page
• Searchable / filterable nav (when the site outgrows the sidebar)

Phase 9 — Install and packaging polish · Queued

• Clearer binary install matrix (macOS arm64 / others as published)
• Version pinning and upgrade notes
• “Doctor / verify install” style page tied to public binaries

Horizon — direction, not dates

Horizon items get phase rows when work actually starts. No undated “soon”.

Baseline already on the site

Still open to polish. “Live” ≠ “frozen.”

Phase 0 — Docs home

• Separate public repo: mturac/alefdocs
• GitHub Pages from main → https://mturac.github.io/alefdocs/
• Native-first branding; private source + public docs/binaries

Phase 1 — Zero-to-run

Book 1–3, quickstart, FAQ. Exit met: alef run main.alef without a private checkout.

Phase 2 — Language book

Book 4–8, language tour, advanced notes. Exit met: core syntax teachable as a language.

Phase 3 — Runtime and core stdlib

Book 9–13, HTTP/AI/DB refs, native API / TicketDesk tutorials. Exit met: small HTTP service + stub AI.

Phase 4 — July 2026 snapshot

What's New · Release notes · macOS codesign install note.

Honest line: AI-native + native-first, not full Go/.NET stdlib parity.

Phase 5 — Stdlib depth (first pass live)

Still to grow here: AES/Ed25519 walkthroughs, full sync primitive catalog, stream composition recipes, job dead-letter playbooks.

What we will not track here

• Private compiler inventory / LR-0 style internal counts
• “Every Go package” as a docs success metric
• Fake completion percentages (“docs are 75% done”) for the language or this site

Suggested reading order

• Install
• First program
• Language tour
• HTTP → AI
• What's New — July 2026
• This roadmap — what we are expanding next on the public docs

Change log