feat(docs): RoboLedger guides for planning, mapping, schedules and the app

[jfrench9]

Summary

The RoboLedger product docs covered connecting, the close and reports, and said almost nothing about planning and forecasting, mapping, schedules or the app itself. This adds seven pages, deepens the existing eight, and adds screenshots. Two small publisher changes make that possible: the product lane can now ship images, and the sidebar groups pages by section.

Product docs publish on merge to main, so merging this puts the pages live on roboledger.ai/docs.

Changes

Publisher (robosystems/scripts/publish_docs.py)

• A product page can show a file from its site's images/ folder. The build rewrites ![alt](images/x.png) to the content CDN and adds the file to the output, the same way the wiki lane already does. An image that does not exist, or sits outside images/, fails the build. A file no page shows is reported as a warning and not shipped. Dotfiles are skipped.
• A page's section front matter groups it in the sidebar. Sections appear in the order of their first page. A site that names no sections produces exactly the single untitled list it did before, so docs/product/robosystems/ is unchanged. The apps already render titled sections for the technical docs, so nothing changes there.
• build_product takes asset_base as an optional fourth argument, defaulting to the public CDN, so the existing caller in tests/scripts/test_product_docs.py is untouched.
• The publish workflow already syncs non-markdown files, so it needs no change.

New pages (docs/product/roboledger/)

• plan-and-forecast.md: scenarios, the four drivers, numbers set directly on a line, per-line growth, what carries forward, the three-statement calculation and its monthly checks, the Plan page, re-running after a close, and what forecasting does not do.
• ask-about-your-books.md: what Claude can read, the difference between live, closed-month and report figures, ratios, and how to ask so an answer can be checked.
• compare-with-public-companies.md: adding the SEC filings graph as a second connection, and making a comparison fair.
• map-your-chart-of-accounts.md: what the first sync maps, reviewing it, and why mapping comes before the close.
• schedules.md: what a schedule is, setting one up with Claude or in the app, ending one early, and how schedules carry into forecasts.
• changes-after-sync.md: transactions edited in QuickBooks after they synced, and the three ways to settle one.
• the-roboledger-app.md: a tour of the app by sidebar section.

Existing pages

• month-end-close.md, reports-and-sharing.md and troubleshooting.md go deeper (the app's side of the close, what happens after it, reading and regenerating a report, seven new troubleshooting entries).
• index.md, connect-your-books.md, what-claude-can-do.md, what-it-needs.md and quickbooks-write-back.md link into the new pages. Every page gained section and a new order; no slug changed, so no URL moves.

Screenshots (docs/product/roboledger/images/, 8 PNGs, about 820 KB)

• Captured from the local stack on the fictional demo company the showcase seeds, in the app's dark theme because the docs pages are dark.
• docs/product/README.md records the conventions: section, where images go, dark theme, a demo company only, alt text as a sentence, and that the pages render markdown only.

Worth a reviewer's eye: each page is a public claim about what the product does today. Pages name no MCP tools, so the pin in test_product_docs.py stays at zero. Bank feeds and custom taxonomies are left out on purpose.

Breaking Changes

None. No API, schema or SDK surface is touched.

Testing

• uv run pytest tests/scripts/test_publish_docs.py tests/scripts/test_product_docs.py: 36 passed, including five new tests for images and sections and the existing check that the real product pages build without errors.
• just docs-build: 54 pages, 63 files, no warnings or errors. Checked the built index.json sections and the rewritten image URLs.
• just test-code: ruff, format and basedpyright clean.
• The full just test-all unit suite was not run; the change is confined to the publish script, its tests and markdown.
• Not verified: the pages rendered on the live site. That can only be seen after the publish workflow runs on merge.

Certification

• I have the right to submit this work under the Apache 2.0 license, and do so. Where any part of it is owned by my employer, I have their permission.

🤖 Generated with Claude Code

[github-actions]

Change classification: normal — platform or application code changed.

A normal change carries a documented automated review on this pull request before merge, in place of a second human approver. The change-classification job requests that review and passes once it has been posted. Recorded by the change-classification job.

[jfrench9]

@claude please review this PR

[claude]

Claude finished @jfrench9's task in 3m 14s —— View job

---

Review: RoboLedger docs depth

• Gather context (PR description, diff, changed files)
• Review publisher changes (robosystems/scripts/publish_docs.py)
• Review new tests (tests/scripts/test_publish_docs.py)
• Review new/changed doc pages for accuracy and conventions
• Post final review

Verdict: looks good, no blocking issues found. This is a well-scoped, carefully-written PR — I did a close read of the publisher diff, the new tests, and all 26 changed files rather than skimming.

Publisher (robosystems/scripts/publish_docs.py)

• The bang/absolute-URL check split (robosystems/scripts/publish_docs.py:551-563) correctly separates "leave untouched" (http/mailto/#/absolute) from "must exist under images/" for local images — matches the new tests (test_images_point_at_the_cdn_and_ship, test_a_missing_or_misplaced_image_is_an_error).
• product_media / shown / unused bookkeeping (:507-538) is scoped correctly per-site inside the loop, dotfiles are skipped, and the "image no page shows" warning path is exercised by a test.
• Section grouping (:512-526) builds entries with (position, slug, section), sorts by (order, slug) before grouping, so "sections appear in the order of their first page" holds even though the outer file loop is alphabetical by filename, not by order. Verified this against test_sections_group_the_sidebar_in_page_order.
• build_product's new asset_base parameter defaults to the existing constant, so the untouched call site in tests/scripts/test_product_docs.py and the just docs-build recipe (no --asset-base passed) both still work.
• Confirmed the claim that the publish workflow needs no change: .github/workflows/publish-docs.yml's upload step already does aws s3 sync ... --exclude "*.md" --exclude "index.json", which covers the new product/{site}/images/... output.

One latent (non-blocking) gap: an image target starting with / bypasses the "must exist under images/" check entirely (:553), so a typo like ![](/images/plan.png) would ship a link to a path that was never rewritten to the CDN, instead of failing the build. Not triggered by this PR — all 11 image references in the new pages correctly use images/... — just worth knowing if a future page fat-fingers a leading slash.

Content

• Cross-checked every sibling-page link ((*.md)) across all 15 roboledger pages against the actual filenames — all resolve, no dead links.
• Checked all order/section front matter across the site: values are unique and cleanly banded by section (Get started 0–4, Work with your books 10–13, Keep the books right 20–24, Reference 30), leaving room to insert future pages without renumbering everything.
• Checked all 11 ![](images/...) references against the 8 shipped PNGs — all match (three images are intentionally reused across pages, e.g. chart-of-accounts.png in both map-your-chart-of-accounts.md and the-roboledger-app.md).
• No backticked kebab-case strings in the new pages, so test_tool_mentions_are_pinned's EXPECTED_TOOL_MENTIONS = 0 correctly stays put.
• Content itself is precise and consistent: the three-way live/closed/report distinction in ask-about-your-books.md, the schedule/forecast/close cross-links, and the restate/catch-up/mark-handled framing in changes-after-sync.md all agree with how the same mechanics are described in month-end-close.md, plan-and-forecast.md and troubleshooting.md. Nothing reads like an aspirational or planned feature.

Not verified

I wasn't able to get uv run pytest or the linked commands approved to execute in this sandbox, so I did not re-run just test-code / pytest tests/scripts/test_publish_docs.py tests/scripts/test_product_docs.py myself — my read of the diff and the new test cases is static. Given the PR body already reports 36 passing tests including the five new ones, and the logic traced above matches what those tests assert, I have no reason to doubt it, but flagging that I couldn't independently confirm it.