Docs: workbook-first UX + fix check/run-id examples

docs/source/index.rst

@@ -5,12 +5,19 @@ LedgerLoom is a small open-source project (MIT license) that teaches accounting
 *and* modern software engineering by building a deterministic, testable ledger
 pipeline.
 
-The documentation is organized into:
+If you are using LedgerLoom as a student, start with the **Workbook**.
 
-- **Start here**: what LedgerLoom is and where it is going
-- **Engine**: the reusable core that powers the chapters
-- **Chapters**: runnable scripts that generate reproducible artifacts
-- **Appendices**: reference material (data model, glossary, cookbook)
+.. toctree::
+   :maxdepth: 2
+   :caption: Workbook (Students)
+
+   workbook/index
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Practical Tooling (CLI)
+
+   practical_tooling/index
 
 .. toctree::
    :maxdepth: 1
@@ -59,13 +66,6 @@ The documentation is organized into:
    ledgerloom_ch17_statement_analysis_summary_statistics
    ledgerloom_ch18_forecasting_planning_basics
 
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Workbook (Hybrid method)
-
-   workbook/index
-
 .. toctree::
    :maxdepth: 1
    :caption: Appendices
@@ -75,4 +75,3 @@ The documentation is organized into:
    ledgerloom_appendix_cookbook
    ledgerloom_appendix_implementation_notes
    ledgerloom_appendix_data_model_reference
-   practical_tooling/index

docs/source/workbook/index.rst

@@ -2,7 +2,7 @@ Financial Accounting — The Hybrid Method with LedgerLoom
 ========================================================
 
 **Subtitle:** Stop Guessing. Start Reconciling.  
-**Version:** 1.0 (compatible with LedgerLoom v0.2.0)
+**Version:** 1.0 (compatible with LedgerLoom v0.3.0)
 
 This workbook teaches *intro* financial accounting using a simple hybrid workflow:
 
@@ -13,14 +13,14 @@ This workbook teaches *intro* financial accounting using a simple hybrid workflo
 .. toctree::
    :maxdepth: 2
 
+   student_quick_start
    workbook_spreadsheet_first_overview
-   workbook_spreadsheet_first_ch01_ch04
-   workbook_data_pack_ch01_startup
-   workbook_spreadsheet_build_ch01_ch04
    workbook_onboarding
    workbook_project_layout
+   workbook_spreadsheet_first_ch01_ch04
+   workbook_spreadsheet_build_ch01_ch04
+   workbook_data_pack_ch01_startup
    workbook_check_your_work_pack
-   student_quick_start
    intro_zero_cost_stack
    ch01_startup
    ch01_equation_transaction

docs/source/workbook/student_quick_start.rst

@@ -25,6 +25,11 @@ These files appear under:
 
 - ``outputs/<run_id>/artifacts/``
 
+.. note::
+   ``ledgerloom check`` writes a standalone report folder to ``outputs/check/<period>/`` (fast feedback).
+   ``ledgerloom build --run-id run1`` writes a complete run folder to ``outputs/run1/`` and repeats the
+   checks inside ``outputs/run1/check/`` for provenance.
+
 .. note::
    LedgerLoom runs best inside a **virtual environment** (venv). This keeps your class setup clean and repeatable.
 
@@ -72,14 +77,18 @@ Linux (Ubuntu/Debian)
 
 .. code-block:: bash
 
-   ledgerloom check --project . --run-id run1
+   ledgerloom check --project .
    ledgerloom build --project . --run-id run1
 
 6) View your outputs
 ^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: bash
 
+   # Standalone check output (fast feedback)
+   ls -1 outputs/check
+
+   # Build output (a named run folder)
    ls -1 outputs/run1/artifacts
 
 Common gotchas (Linux)
@@ -150,14 +159,18 @@ Then activate again:
 
 .. code-block:: powershell
 
-   ledgerloom check --project . --run-id run1
+   ledgerloom check --project .
    ledgerloom build --project . --run-id run1
 
 6) View your outputs
 ^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: powershell
 
+   # Standalone check output (fast feedback)
+   dir outputs\check
+
+   # Build output (a named run folder)
    dir outputs\run1\artifacts
 
 Common gotchas (Windows)
@@ -216,14 +229,18 @@ Then:
 
 .. code-block:: bash
 
-   ledgerloom check --project . --run-id run1
+   ledgerloom check --project .
    ledgerloom build --project . --run-id run1
 
 6) View your outputs
 ^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: bash
 
+   # Standalone check output (fast feedback)
+   ls -1 outputs/check
+
+   # Build output (a named run folder)
    ls -1 outputs/run1/artifacts
 
 Common gotchas (macOS)

docs/source/workbook/workbook_project_layout.rst

@@ -24,7 +24,17 @@ A typical workbook project looks like this:
          transactions.csv
          adjustments.csv
      outputs/
+       check/
+         2026-01/
+           checks.md
+           staging.csv
+           staging_issues.csv
+           unmapped.csv
+           reclass_template.csv
        run1/
+         source_snapshot/
+         check/
+         trust/
          artifacts/
            entries.csv
            trial_balance_unadjusted.csv
@@ -51,10 +61,19 @@ What each part means
 ``inputs/<period>/adjustments.csv``
   Your adjusting entries table (often empty at the start of Chapter 1).
 
+``outputs/check/<period>/``
+  The report folder produced by ``ledgerloom check`` when run by itself.
+
+``outputs/<run_id>/``
+  The folder produced by ``ledgerloom build --run-id <run_id>``.
+
 ``outputs/<run_id>/artifacts/``
   The CSV results LedgerLoom generates. These are meant to be opened in Excel/Sheets
   and compared to your workbook.
 
+``outputs/<run_id>/check/``
+  The same check output, captured inside a build run for provenance.
+
 What is a run_id?
 -----------------
 
@@ -99,14 +118,20 @@ Common workflow (what you actually do)
 
 .. code-block:: bash
 
-   ledgerloom check --project my_books --run-id run1
+   ledgerloom check --project my_books
+
+   # Standalone check output is written to:
+   #   my_books/outputs/check/<period>/
 
 3) Build artifacts:
 
 .. code-block:: bash
 
    ledgerloom build --project my_books --run-id run1
 
+   # Build output is written to:
+   #   my_books/outputs/run1/
+
 4) Open artifacts in Excel/Sheets and compare.
 
 If something is wrong, don’t panic
@@ -129,4 +154,3 @@ Next: Student Quick Start
 Go to:
 
 :doc:`student_quick_start`
-

src/ledgerloom/cli.py

@@ -94,7 +94,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     b = sub.add_parser(
         "build",
-        help="Create a run folder (snapshot + check + trust + postings + trial_balance + statements)",
+        help="Create a run folder (snapshot + check + trust + artifacts)",
     )
     b.add_argument(
         "--project",
@@ -280,7 +280,7 @@ def main(argv: Sequence[str] | None = None) -> int:
             parts.append("trial_balance")
         if inc.exists() and bs.exists():
             parts.append("statements")
-        print(f"Build OK ({' + '.join(parts)}). Next: closing entries.")
+        print(f"Build OK ({' + '.join(parts)}). See artifacts/ for generated CSVs.")
         return 0
 
 

src/ledgerloom/docs_helper.py

@@ -46,4 +46,4 @@ def open_local_docs() -> None:
 
 def open_online_docs() -> None:
     """Open the Read the Docs site for LedgerLoom."""
-    webbrowser.open_new("https://ledgerloom.readthedocs.io/en/latest/")
+    webbrowser.open_new("https://ledgerloom.readthedocs.io/en/latest/workbook/student_quick_start.html")