Iter 13f: rustdoc polish for ailang-codegen + ail CLI

Third docwriter mission (combined). Pure rustdoc additions, no
API or behaviour change.

ailang-codegen (113 LOC of doc):
- Crate root: intra-doc links (emit_ir, lower_workspace,
  CodegenError::MissingEntryMain) + precondition note (both
  entry points assume type-checked input).
- /// on CodegenError + every variant, naming AST trigger.
- /// on emit_ir and lower_workspace (single vs multi-module
  split, cross-linked).

ail CLI (49 LOC of doc):
- Module-level //! expanded from 5 lines to full subcommand
  list with one-liners (11 subcommands verified against Cmd
  enum), clang-on-PATH note, design-intent paragraph.

Verification: cargo doc --no-deps zero warnings (also under
RUSTDOCFLAGS='-D rustdoc::broken_intra_doc_links'); build green;
tests 64/64 + 3 ignored doctests green. Diff is 100% doc lines
(verified by filtering).

Findings (not fixed; orchestrator-deferred):
- CodegenError::Internal is one catch-all variant for ~30
  invariant-violation sites; splitting would help test
  ergonomics but is out of doc scope.
- emit_ir synthesises a Workspace with root_dir="."; harmless
  today, surfaces if codegen ever reads root_dir.

Process note: my brief said the CLI had 9 subcommands; agent
found and documented 11. Useful counter-pressure on orchestrator
sloppiness — recorded in JOURNAL.

Workspace-wide rustdoc invariant (DESIGN.md item 6) now
load-bearing across all four crates. Docwriter shifts from
sweep to maintenance mode going forward.

Next: 14a (polymorphic list_map using Iter-13a parameterised
ADTs) is unblocked.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

crates/ail/src/main.rs

@@ -1,8 +1,51 @@
 //! `ail` — CLI for AILang.
 //!
-//! Subcommands are sliced so that each individual tool gives the LLM a
-//! small, focused context (manifest = overview; describe =
-//! detail; emit-ir = exact machine view; build = pipeline validation).
+//! The user-facing toolchain binary. Wraps the `ailang-core`
+//! (loader/AST/hashing), `ailang-check` (typechecker), and
+//! `ailang-codegen` (LLVM IR emitter) crates into a set of
+//! deliberately small subcommands. The slicing follows the project's
+//! LLM-author audience: each individual tool gives the LLM the
+//! minimum context needed for one task — `manifest` for an overview,
+//! `describe` for a single def, `emit-ir` for the exact machine view,
+//! `build` for full-pipeline validation. No "do everything" command.
+//!
+//! # Subcommands
+//!
+//! - `manifest` — compact symbol table of a module (or workspace);
+//!   one line per def with type, effects, hash.
+//! - `render` — pretty-print a `.ail.json` module as the textual
+//!   `.ail` projection.
+//! - `describe` — full detail of a single definition, JSON or text.
+//! - `deps` — static call edges per def (or for one named def);
+//!   workspace mode emits cross-module edges.
+//! - `check` — load + schema-validate + typecheck. Emits structured
+//!   diagnostics with `--json`; exit code 1 on any error.
+//! - `emit-ir` — write LLVM IR (`.ll`) for the module. Useful for
+//!   inspecting the generated code without invoking `clang`.
+//! - `build` — full pipeline (`check` → `emit-ir` → `clang`) producing
+//!   a native binary at `--out`.
+//! - `run` — `build` into a tempdir and execute the binary; passes
+//!   the binary's exit code through.
+//! - `builtins` — list the built-in effect ops (`io/print_int`,
+//!   `io/print_bool`, `io/print_str`, ...) with their signatures.
+//! - `diff` — semantic, hash-based module/workspace diff. Works even
+//!   when a module doesn't currently typecheck.
+//! - `workspace` — load an entry module's transitive imports and list
+//!   the reachable modules with hash and def count.
+//!
+//! # External tooling
+//!
+//! `build` and `run` shell out to `clang` to link the emitted IR into
+//! a native binary. `clang` must therefore be on `PATH` for those
+//! subcommands; the other subcommands have no external dependencies.
+//!
+//! # rustdoc surface
+//!
+//! This is a binary crate with no `pub` items. The user-facing CLI
+//! help is generated by `clap` from the `#[command(...)]` doc
+//! comments on `Cmd` variants and surfaces as `ail --help`, not as
+//! rustdoc. Private helpers are intentionally undocumented at the
+//! rustdoc level — read the source.
 
 use anyhow::{Context, Result};
 use clap::{Parser, Subcommand};