14 · Generate a workspace — goals & curricula

alix deck generate --trace --plan lists central traces. alix workspace generate goes a layer up: give it a directory and a goal and it explores the source first — one AI planning pass — and prints an ordered learning plan: the facts decks and traces worth authoring to reach that goal, dependency-ordered.

alix workspace generate . --plan                                      # a plan to understand the whole source
alix workspace generate . --plan --goal "how review scheduling works" # a narrow goal → a focused subset

Each item is tagged [trace] or [deck], chosen by the shape of the knowledge: a path you predict hop by hop becomes a trace; a table of facts — a config’s knobs, a store’s on-disk format — becomes a facts deck. Each carries its requires: prerequisites (the list is a valid dependency order, foundations first) and a source: scope. The --goal scopes coverage: a broad goal spans every subsystem; a narrow one collapses to its slice and traces it in more detail. --plan is read-only — it prints the plan and stops, so you can author the items yourself (alix deck generate a trace or a facts deck per item).

Building the workspace

alix workspace generate . --goal "how review scheduling works" --into ~/decks/scheduling/
alix workspace generate . --source-url https://example.com/project --into ~/decks/project/

Without --plan, you always get a workspace, whatever the plan’s size: a one-item plan still writes the manifest, the assets, and that one deck, ready to grow. (For one deck from a directory taken whole, with no planning pass at all, run alix deck generate <dir>.) A workspace build goes like this: the plan prints, alix confirms (Build N items into <dir>? [y/N] — -y skips it), then goes all the way — it explores the source once and reuses that single session to fill every item — predict-verify checkpoints for the traces, fact cards for the decks — so the workspace comes out review-ready in one command: an alix.toml (carrying the goal; --title names it) and one file per item under decks/: a trace: deck per trace and a source: facts deck per deck, wired together with requires: so they unlock in dependency order, each source: pointing back at the real source. Writing the whole set from one understanding keeps the items coherent (each builds on its prerequisites instead of repeating them). Before the hidden staging workspace becomes visible, Alix initializes every complete member and freezes its evidence. Cited excerpts (from files and directories alike) and local card images land below each member’s assets/deck-<token>/ directory. A missing or changed required source aborts publication instead of leaving a live or partially frozen workspace. --source-url <URL> records a public source in the workspace defaults. Tutor and exam calls can use it for wider context and staleness checks after the local generation source is gone, while review continues to use the frozen assets.

The destination is --into <dir>, defaulting to a folder named after the source under your decks directory.

Populated destinations

Pointing a build at a destination that already has files never blocks the run or loses anything: alix builds into a scratch staging folder next to it first, then moves the new member files into decks/ one by one. A name that’s already there keeps your existing file untouched — the new version stays behind in the staging folder, reported at the end so you can compare and move it in by hand — while everything else lands normally. Pass --force to overwrite collisions instead.

This is the tool’s high-water mark: name what you want to understand, and alix assembles a dependency-ordered curriculum of facts and traces — gated by mastery — that you climb.

The explore walk — --trace

Before you even know what to trace, alix deck generate <source> --trace builds a short tour of the source’s shape, written as a trace deck: you predict what kind of program it is (from the manifest), its domain nouns (from the module list), how it’s driven (the entry point), its spine (the central file), and finally the first paths worth tracing — each hop revealing the real lines. It’s written to a file (-o, default explore.md; --into places it inside a workspace), and you walk it from the web picker: run alix and pick it.