Docs: Workbook centerpiece pages + clearer navigation

docs/source/workbook/index.rst

@@ -12,18 +12,32 @@ This workbook teaches *intro* financial accounting using a simple hybrid workflo
 
 .. toctree::
    :maxdepth: 2
+   :caption: Start here
 
    student_quick_start
-   workbook_spreadsheet_first_overview
+   workbook_learning_path
    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
-   intro_zero_cost_stack
+   workbook_artifacts_reference
+   workbook_troubleshooting
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Workbook chapters (hybrid method)
+
    ch01_startup
    ch01_equation_transaction
    ch02_journal_to_trial_balance
    ch03_adjusting_entries
    ch04_closing_and_post_close
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Optional tracks and packs
+
+   workbook_spreadsheet_first_overview
+   workbook_spreadsheet_first_ch01_ch04
+   workbook_spreadsheet_build_ch01_ch04
+   workbook_data_pack_ch01_startup
+   workbook_check_your_work_pack
+   intro_zero_cost_stack

docs/source/workbook/student_quick_start.rst

@@ -33,6 +33,13 @@ These files appear under:
 .. note::
    LedgerLoom runs best inside a **virtual environment** (venv). This keeps your class setup clean and repeatable.
 
+Where to go next
+----------------
+
+- :doc:`workbook_learning_path` — the “golden path” for this course
+- :doc:`workbook_artifacts_reference` — what each output CSV means
+- :doc:`workbook_troubleshooting` — common errors and quick fixes
+
 Linux (Ubuntu/Debian)
 ---------------------
 

docs/source/workbook/workbook_artifacts_reference.rst

@@ -0,0 +1,77 @@
+Workbook Artifacts Reference
+============================
+
+LedgerLoom produces two kinds of outputs:
+
+1) **Check outputs** (fast feedback) — written by ``ledgerloom check``
+2) **Run outputs** (a full snapshot) — written by ``ledgerloom build --run-id <run_id>``
+
+Check outputs (``outputs/check/<period>/``)
+-------------------------------------------
+
+These files help you fix problems *before* you build a run folder:
+
+- ``checks.md``  
+  A human-readable report: what LedgerLoom found, and what to do next.
+
+- ``staging.csv``  
+  Your inputs normalized into a consistent table format.
+
+- ``staging_issues.csv``  
+  Row-level problems (missing fields, invalid dates, bad numbers).
+
+- ``unmapped.csv``  
+  Rows LedgerLoom could not map cleanly (often an account name mismatch).
+
+- ``reclass_template.csv``  
+  A “fill-in-the-blanks” template used for reclassing/mapping workflows.
+
+Run outputs (``outputs/<run_id>/artifacts/``)
+---------------------------------------------
+
+These are the canonical workbook artifacts you compare against your spreadsheet:
+
+- ``entries.csv``  
+  Your journal entries in a normalized, deterministic format.
+
+- ``trial_balance_unadjusted.csv``  
+  Trial balance after posting **transactions** only.
+
+- ``trial_balance_adjusted.csv``  
+  Trial balance after posting **transactions + adjustments**.
+
+- ``closing_entries.csv``  
+  The closing entry set that resets temporary accounts (revenue/expenses/dividends).
+
+- ``trial_balance_post_close.csv``  
+  Post-close trial balance (balance-sheet accounts only).
+
+Where “trust” fits (``outputs/<run_id>/trust/``)
+------------------------------------------------
+
+LedgerLoom also writes a trust package (hashes + manifests) so a run folder is a
+reproducible snapshot.
+
+As a student, you usually only need this when:
+
+- you’re submitting a “run folder” as proof, or
+- you want to confirm you built against the intended inputs.
+
+If you’re curious, start with:
+
+- ``trust/run_meta.json`` — what was built, when, and from which sources
+- ``trust/manifest.json`` — the list of artifacts and their hashes
+
+How to use this page while working
+----------------------------------
+
+If something breaks:
+
+1) run ``ledgerloom check``  
+2) open ``outputs/check/<period>/checks.md``  
+3) fix the first error you see, then re-run
+
+If you’re unsure which output to compare:
+
+- use **trial balances** to validate totals
+- use **entries.csv** to validate the “shape” of the journal (dates, accounts, signs)

docs/source/workbook/workbook_check_your_work_pack.rst

@@ -1,10 +1,12 @@
-Optional: Check Your Work Pack (Ch01 Startup)
-=============================================
+Optional: Check Your Work Packs (Ch01–Ch04)
+===========================================
 
 This workbook is meant to be a *learning* experience, not a “gotcha” test.
 If you have a low tolerance for frustration (or you just want to confirm you’re on the right track),
 use the downloads below to compare your work against a known-good reference.
 
+These packs are available for **Ch01–Ch04** and include a completed spreadsheet plus reference outputs.
+
 **Canonical dataset contract:** each Workbook chapter has a *canonical dataset* under
 ``examples/workbook/<chapter_slug>/`` — treat this as the answer key. The accompanying
 “reference outputs” ZIPs are generated by running ``ledgerloom build --run-id r1`` for that

docs/source/workbook/workbook_learning_path.rst

@@ -0,0 +1,48 @@
+Workbook Learning Path (Spreadsheet + LedgerLoom)
+=================================================
+
+This is the **main path** for the workbook: you do the accounting in your spreadsheet,
+then use LedgerLoom to verify it and produce clean CSV artifacts you can compare.
+
+The loop you will repeat
+------------------------
+
+1) **Draft** in Sheets/Excel (transactions + adjustments + optional closing).
+2) **Export CSVs** using the workbook template headers.
+3) Run:
+
+   .. code-block:: bash
+
+      ledgerloom check --project .
+      ledgerloom build --project . --run-id run1
+
+4) **Reconcile**: compare your spreadsheet totals to LedgerLoom outputs. Fix mistakes, re-run.
+
+Where to start
+--------------
+
+If you are brand new, do this in order:
+
+- :doc:`student_quick_start` (install + your first run)
+- :doc:`ch01_startup` (a runnable, known-good project)
+- :doc:`ch02_journal_to_trial_balance` (journal → TB)
+- :doc:`ch03_adjusting_entries` (accrual adjustments → adjusted TB)
+- :doc:`ch04_closing_and_post_close` (closing → post-close TB)
+
+If you want to learn the accounting cycle **without any tooling first**, use the
+Spreadsheet-First track: :doc:`workbook_spreadsheet_first_overview`.
+
+What “success” looks like
+-------------------------
+
+- ``ledgerloom check`` produces a review package under ``outputs/check/<period>/``.
+- ``ledgerloom build --run-id run1`` produces a full run folder under ``outputs/run1/``.
+- Your spreadsheet and LedgerLoom artifacts should agree on totals (trial balance and post-close TB).
+
+Next: learn the output files
+----------------------------
+
+Before you go deeper, skim:
+
+- :doc:`workbook_artifacts_reference` — what each CSV output means
+- :doc:`workbook_troubleshooting` — common mistakes and how to recover quickly

docs/source/workbook/workbook_troubleshooting.rst

@@ -0,0 +1,83 @@
+Workbook Troubleshooting
+========================
+
+This page is a student-friendly checklist for the most common problems.
+
+I ran ``ledgerloom check`` and it failed
+----------------------------------------
+
+Start here:
+
+1) Open ``outputs/check/<period>/checks.md``.
+2) Fix the *first* issue listed (later issues often cascade from earlier ones).
+3) Run ``ledgerloom check`` again.
+
+I can’t find my outputs
+-----------------------
+
+- ``ledgerloom check`` writes to: ``outputs/check/<period>/``
+- ``ledgerloom build --run-id run1`` writes to: ``outputs/run1/``
+
+Your workbook artifacts live in:
+
+- ``outputs/<run_id>/artifacts/``
+
+I see ``unmapped.csv``
+----------------------
+
+This usually means LedgerLoom didn’t recognize something in your inputs (often an
+account name mismatch).
+
+Do this:
+
+1) Open ``outputs/check/<period>/unmapped.csv``.
+2) Compare the ``account`` values to ``config/chart_of_accounts.yaml``.
+3) Fix the spelling / punctuation / account root (``Assets:``, ``Liabilities:``, etc.).
+4) Re-run ``ledgerloom check``.
+
+My trial balance doesn’t balance
+--------------------------------
+
+If your spreadsheet trial balance debits ≠ credits:
+
+- Look for a sign error (debit entered as credit or vice versa).
+- Look for a missing “pair” row in a journal entry (every entry must balance).
+- Compare your spreadsheet journal lines against ``outputs/<run_id>/artifacts/entries.csv``.
+
+I used ``--run-id`` with ``check`` and got an error
+---------------------------------------------------
+
+``--run-id`` belongs to ``build``, not ``check``:
+
+.. code-block:: bash
+
+   ledgerloom check --project .
+   ledgerloom build --project . --run-id run1
+
+LedgerLoom says an account root is invalid
+------------------------------------------
+
+LedgerLoom expects account names to start with one of these roots:
+
+- ``Assets:``
+- ``Liabilities:``
+- ``Equity:``
+- ``Revenue:``
+- ``Expenses:``
+
+Example:
+
+- ✅ ``Assets:Cash``
+- ❌ ``Cash`` (missing root)
+
+Still stuck?
+------------
+
+- Re-run ``ledgerloom check`` and read ``checks.md`` carefully.
+- If you are working from a workbook chapter, compare against the
+  :doc:`workbook_check_your_work_pack`.
+- If you think it’s a bug, open an issue on GitHub with:
+
+  - your LedgerLoom version (``ledgerloom --version``)
+  - the ``checks.md`` file
+  - a minimal set of inputs that reproduces the issue