Expand BUS Core wiki and bump internal version

Author: truegoodcraft

CHANGELOG.md

@@ -26,6 +26,12 @@
 - Future Core updates will focus on bug fixes, safety, security/trust, backup and data protection, tester blockers, update/release reliability, small UX clarification, and documentation. New major workflow or domain expansion moves to BUS Pro discovery.
 - Still not included: full POS, full accounting, QuickBooks/Wave sync, automatic reorder, full job scheduling, cloud accounts, cloud sync, telemetry, payment links, customer portals, or recurring billing.
 
+### Operator Wiki Documentation
+
+- Expanded the BUS Core Wiki with operator-focused getting-started, first-shop workflow, inventory, recipes, manufacturing, Finance, backup/restore, local-first trust, updates, troubleshooting, and product-boundary guidance.
+- Cross-linked the Wiki around the verified v1.3.2 material-to-product workflow and replaced stale draft wording without changing runtime, API, security, update, backup/restore, or data behavior.
+- Bumped `INTERNAL_VERSION` from `1.3.2.0` to `1.3.2.1` for the documentation trace while leaving public `VERSION` at `1.3.2`.
+
 ## [1.3.1] - 2026-06-18
 
 ### Release Guard Fix

core/version.py

@@ -23,7 +23,7 @@
 VERSION = "1.3.2"
 
 # Internal working revision. Agents may bump this on meaningful repo changes.
-INTERNAL_VERSION = "1.3.2.0"
+INTERNAL_VERSION = "1.3.2.1"
 
 __all__ = ["VERSION", "INTERNAL_VERSION"]
 

wiki/Backups-and-Data-Persistence.md

@@ -1,45 +1,42 @@
-> Status: Draft
+# Backup and Restore
 
-# Backups and Data Persistence
+BUS Core is local-first, so the operator is responsible for protecting local business data. Make a backup before Start Fresh, restore, major host changes, or container recreation.
 
-This page is a draft summary of what operators should currently treat as important persistence concerns.
+## Create an Encrypted Export
 
-## What Matters Most
+1. Open **Settings > Administration > Backup Export**.
+2. Enter a non-empty backup password.
+3. Select **Export**.
+4. Confirm the new file appears under available exports.
+5. Store the password separately and appropriately for your shop.
 
-The main BUS Core database is the critical durable business state.
+On Windows, exports are stored under `%LOCALAPPDATA%\BUSCore\exports` as encrypted `.db.gcm` files. The export is password-based AES-GCM; losing the password can make the backup unusable.
 
-Before using **Start Fresh Shop** or any reset-like workflow, export a backup from **Settings -> Administration -> Backup Export**. Enter a backup password, select **Export**, and confirm the saved export appears in the recent exports list before resetting real-shop data.
+## Restore: Preview, Then Commit
 
-For Docker-based setups, the primary persistence target should be:
+1. Open **Settings > Administration > Restore (Preview then Commit)**.
+2. Select a backup file or an available export and enter its password.
+3. Select **Preview**. Preview validates the container and schema and shows table counts without replacing the active database.
+4. Review the result and path.
+5. Select **Commit (archives journals)** only when you intend to replace the active database.
+6. Restart BUS Core when the UI reports that restart is required.
 
-```text
-/data/app.db
-```
+Commit enters maintenance mode, replaces database state through the guarded restore path, archives existing journals, and recreates empty journals. It is not an undo button. Keep the source export until you have verified the restored shop.
 
-## SQLite Sidecar Files
+## Windows Path Note
 
-Depending on runtime state, SQLite sidecar files may also exist alongside the main database, including files such as WAL or SHM companions.
+v1.3.2 fixed export, preview, and restore handling for Windows paths containing spaces or `#`. Use the in-app staged upload/preview flow rather than moving database files by hand.
 
-If those files exist during live operation, treat them as part of the active database state rather than as disposable clutter.
+## Docker Persistence
 
-## Before You Rely On Reset Or Update Flows
+The default container database is `/data/app.db` with `BUS_DB=/data/app.db`. Mount `/data` to durable host storage and verify the mount survives container recreation. SQLite may use active WAL/SHM sidecar files; do not copy or discard live database files casually. Prefer the in-app encrypted export.
 
-Before relying on container reset, recreation, or update workflows, make sure you understand:
+## Safety Boundaries
 
-- where the database file is actually stored
-- whether sidecar database files are present
-- whether your backup or export process captures what you expect
-- whether your storage mount remains attached after container changes
+- Preview before every commit.
+- Do not treat a filename in the export list as proof that you know its password or that an off-device copy exists.
+- Test restore in an appropriate environment before depending on a backup plan.
+- A local export on the same failing disk is not a complete disaster-recovery strategy.
+- BUS Core does not provide hosted backup or cloud sync.
 
-## Pending Audit Scope
-
-Exact persistence requirements for non-database state are still pending audit.
-
-That means operators should not yet assume a final answer for all BUS Core runtime state, including possible logs, journals, exports, config, secrets, session state, or future integration data.
-
-## Current Practical Advice
-
-- Persist `/data` when using Docker.
-- Verify that `BUS_DB=/data/app.db` is set.
-- Test restore assumptions before treating a reset or update flow as safe.
-- Keep this page in draft status until the non-DB persistence surface is audited more completely.
+Next: [Trust, Security, and Local-First](Trust-Security-and-Local-First.md).

wiki/FAQ.md

@@ -1,31 +1,57 @@
-> Status: Draft
+# Troubleshooting and FAQ
 
-# FAQ
+## Why do I need a product before a recipe?
 
-## Is BUS Core cloud-based?
+A recipe must point to an existing Output Product. Create the inventory item, mark **This is a product**, save it, then create the recipe.
 
-Draft answer: BUS Core is intended to be local-first rather than a cloud-first hosted service.
+## Why did manufacturing fail with a shortage?
+
+At least one recipe input did not have enough available stock. Read the need, have, and missing quantities, then stock in the input, reduce the run, or correct the recipe. A failed shortage run does not partially consume inputs or create output.
+
+## Why does sale price matter?
+
+For Stock Out reason **Sold**, price supplies sales revenue used by Finance. The product's usual price is a starting point, not a locked price. BUS Core warns when the entered price is lower.
+
+## Is BUS Core a POS?
+
+No. It can record product stock-out and related sale value, but it is not a full checkout, payment-processing, receipt, or register system.
+
+## Is it accounting software?
+
+No. Finance provides operational sales, returns, COGS, expense, and profit visibility. It is not full double-entry accounting, bank reconciliation, payroll, or tax software.
+
+## Where is my data?
+
+Packaged Windows production data is under `%LOCALAPPDATA%\BUSCore\app\app.db`; demo data uses `app_demo.db`. Docker normally uses `/data/app.db`, which must be persistently mounted. See [Backup and Restore](Backups-and-Data-Persistence.md).
+
+## Does BUS Core use cloud sync or telemetry?
+
+No. Core has no forced cloud, cloud sync, or telemetry. Explicitly configured network features such as update checks or supported integrations can make their required requests.
 
 ## Does it require an account?
 
-Draft answer: local use is intended to work without a required cloud account. Final user-facing wording should stay aligned with canonical product docs.
+No hosted account is required. BUS Core can operate in unclaimed local mode; an operator can also claim an instance and configure local users and permissions.
+
+## Can multiple users use it?
+
+Local user accounts and permissions exist, but the default packaged and Docker deployments are loopback-only and are not a supported general multi-user network service. Do not expose BUS Core to a LAN or the internet based only on the presence of user accounts.
 
-## Can I run it locally?
+## Can I use QuickBooks or Wave?
 
-Draft answer: yes, local operation is the main expected model.
+BUS Core has no direct QuickBooks/Wave sync. Finance CSV export can support a separate manual bookkeeping process.
 
-## Can I run it in Docker?
+## Why can I not mark this stock-out as Sold?
 
-Draft answer: yes, but Docker deployment is still beta/community-tested. See [Docker Install](Docker-Install.md).
+Sold stock-out is currently supported for count items. For non-count items, use the accurate loss/theft/other reason, or model a count-based sale product when that reflects the real workflow.
 
-## Where is my data stored?
+## What does Core frozen/stability mode mean?
 
-Draft answer: this depends on how BUS Core is deployed. Docker users should review [Backups and Data Persistence](Backups-and-Data-Persistence.md). A fuller persistence audit is still pending.
+Core remains maintained and useful. After v1.3.2, work focuses on reliability, security, data safety, release hygiene, documentation, tester blockers, and small clarity fixes. Major new workflow discovery moves to BUS Pro.
 
-## How do I back it up?
+## Is Docker supported?
 
-Draft answer: backup guidance is still being refined. Start with [Backups and Data Persistence](Backups-and-Data-Persistence.md) and verify your storage assumptions before relying on reset or update flows.
+The Docker image and default Compose configuration exist, but Docker/Synology guidance remains community-tested. Keep the default loopback binding and persist `/data`. See [Docker Install](Docker-Install.md).
 
-## Where do I report bugs?
+## Where do I report a problem?
 
-Use [Bug Reports](Bug-Reports.md).
+Use [Bug Reports](Bug-Reports.md). Include the BUS Core version, install method, what you attempted, what happened, and whether demo or real-shop data was active.

wiki/Finance-Guide.md

@@ -0,0 +1,31 @@
+# Finance Guide
+
+Finance gives an operational view of the business events recorded in BUS Core. It is not a complete accounting ledger or tax system.
+
+## What It Shows
+
+- Gross Sales, Returns, and Net Sales
+- COGS and Gross Profit
+- Expenses and Net Profit
+- Manufacturing run and produced-item context
+- A transaction feed including supported sales, refunds, expenses, manufacturing runs, and inferred purchases
+
+COGS means the inventory cost assigned to sold goods. Gross Profit is sales after returns and COGS. Net Profit also accounts for expenses recorded in BUS Core. Results are only as complete as the events and costs you record.
+
+## Why Sale Price Matters
+
+When Stock Out uses reason **Sold**, the sale price supplies revenue for the cash event. If the product has a usual price, BUS Core pre-fills it and warns non-blockingly when the entered amount is lower. A missing or incorrect sale price makes profit reporting less useful.
+
+## Date Ranges
+
+Enter From and To dates or use **Last 30 days**, **This month**, **Last month**, **This quarter**, **Last quarter**, or **This year**. Select **Refresh** after choosing a custom range.
+
+## CSV Export
+
+Select **Export CSV** to download the Finance transaction export for the selected date range. Use it for review or transfer into your own bookkeeping process; it is not direct QuickBooks or Wave synchronization.
+
+## Boundary
+
+BUS Core does not replace double-entry accounting, bank reconciliation, payroll, tax filing, tax advice, or an accountant. Reconcile BUS Core's operational figures with your accounting system.
+
+Next: [Backup and Restore](Backups-and-Data-Persistence.md).

wiki/First-Shop-Workflow.md

@@ -0,0 +1,51 @@
+# First Shop Workflow
+
+Use one simple example to learn the whole path. This example makes one finished product from one stocked material.
+
+## 1. Add a Vendor
+
+Open **Inventory**, then create a vendor/contact while adding an item or through the available vendor controls. Use the supplier you buy the material from. Vendors provide purchasing context; they are not stock themselves.
+
+## 2. Add a Raw Material
+
+Select **+ Add Item**. Name the material clearly, choose its dimension and unit, assign the vendor if useful, and save it. Stock the material in with a quantity and unit cost. That receipt creates a costed batch.
+
+Example: `Hardwood blank`, count unit `ea`, 10 on hand at $4.00 each.
+
+## 3. Add the Product
+
+Add another inventory item for what you sell. Check **This is a product** and enter its usual sale price.
+
+Example: `Finished serving board`, count unit `ea`, usual price $35.00.
+
+The product must exist before its recipe because the recipe needs an Output Product to point to.
+
+## 4. Create a Recipe
+
+Open **Recipes** and create a recipe such as `Serving board - standard`. Select the finished product as **Output Product**, set the output quantity and unit, and add the material rows the run consumes.
+
+Keep product and recipe names distinct. The product is stocked and sold; the recipe is the instruction for making it.
+
+## 5. Manufacture
+
+Open **Manufacturing**, choose the recipe and run quantity, then submit the run. BUS Core consumes the required material batches FIFO and adds a costed batch of the output product. History identifies runs as `Run #N`.
+
+To learn the safety behavior, you can first request more than is available. A shortage names the item and shows need, have, and missing quantities. The failed run does not partially consume inputs or create output. Reduce the run or stock in more material, then try again.
+
+## 6. Stock Out a Sale
+
+Open **Inventory > Stock Out**, select the product, choose reason **Sold**, enter the quantity, and confirm the sale price. For count items, BUS Core starts with the product's usual price when one is set. A lower price produces a warning but can still be used.
+
+Reasons such as loss, theft, or other reduce inventory without representing a normal sale. Sold is currently supported for count items.
+
+## 7. Review Finance
+
+Open **Finance** and choose a date preset such as **Last 30 days**. Review Gross Sales, Net Sales, COGS, Gross Profit, Expenses, and Net Profit. The sale price supplies revenue; FIFO input cost flows through manufacturing into the product cost and then COGS when sold.
+
+Finance is operational visibility, not a replacement for bookkeeping, tax filing, or professional accounting advice. See [Finance Guide](Finance-Guide.md).
+
+## 8. Back Up
+
+Open **Settings > Administration > Backup Export**, create an encrypted export, and confirm it appears under available exports.
+
+Next: [Inventory Guide](Inventory-Guide.md) and [Backup and Restore](Backups-and-Data-Persistence.md).

wiki/Getting-Started.md

@@ -1,60 +1,36 @@
 # Getting Started
 
-BUS Core is local-first shop infrastructure for inventory, recipes, manufacturing, and cost visibility. It is not a hosted SaaS account and it is not a full POS or accounting package.
+BUS Core is a downloadable, local-first app for inventory, recipes, manufacturing, and cost visibility. It is not a hosted SaaS account, full POS, or full accounting package.
 
-Core is feature-frozen and stability-focused after v1.3.2. It remains maintained, open-source, local-first infrastructure; future Core updates focus on safety, reliability, tester blockers, data protection, release hygiene, small UX clarification, and documentation. New major workflow or domain expansion moves to BUS Pro discovery.
+## 1. Choose an Install
 
-## Choose Your Install Path
+- [Windows Install](Windows-Install.md) for the packaged local Windows app.
+- [Docker Install](Docker-Install.md) for a container on the same machine.
+- [Synology NAS Docker Setup (Beta)](Synology-NAS-Docker-Setup-Beta.md) only if you are testing that community deployment.
 
-- [Windows Install](Windows-Install.md) for a local Windows setup.
-- [Docker Install](Docker-Install.md) for a container-based setup.
-- [Synology NAS Docker Setup (Beta)](Synology-NAS-Docker-Setup-Beta.md) if you are specifically testing on Synology NAS.
+Keep the default service on the machine's loopback interface. BUS Core's default setup is not a supported public-server or general multi-user network deployment.
 
-## First Launch
+## 2. Choose Demo or Real-Shop Data
 
-On first launch, choose the path that matches what you are doing:
+On first launch:
 
-- Use demo mode to explore seeded sample data.
-- Use Start Fresh when you are ready to create or reset the real-shop database.
-- Export a backup first from Settings -> Administration -> Backup Export if you need to keep existing real-shop data.
+- **Demo mode** uses a separate sample database. Use it to explore without mixing sample records into real-shop data.
+- **Start Fresh** switches to the production database and initializes a fresh real-shop workspace.
 
-Demo data is separate from the real-shop database.
+Start Fresh is a reset-like operation. If real-shop data already exists, first open **Settings > Administration > Backup Export**, enter a backup password, export, and confirm the export appears in the list.
 
-## First Workflow
+## 3. Complete One Small Workflow
 
-Run this path once before entering a large catalog:
+Do not enter the full catalog yet. Add one vendor, one material, one product, one recipe, one manufacturing run, and one sale. The [First Shop Workflow](First-Shop-Workflow.md) walks through the sequence.
 
-1. Add a vendor from Inventory or while creating an item.
-2. Add a raw material with an opening batch and unit cost.
-3. Add a product, check "This is a product", and enter its usual sale price.
-4. Open Recipes and create a recipe.
-5. Select the product as the Output Product.
-6. Add the raw material or component rows the recipe consumes.
-7. Open Manufacturing and select the recipe.
-8. Try a shortage case first if you want to verify the warning path.
-9. Run a successful manufacturing pass and confirm stock changes.
-10. Stock out the product as sold.
-11. Confirm the sale price starts from the usual product price and warns if you enter less.
-12. Open Finance and review sales, COGS, gross profit, and date presets.
-13. Check Settings -> Administration -> Backup Export, update status, Help, support, and report-issue links.
+## 4. Know Where Data Lives
 
-## Key Words
+On packaged Windows installs, the production database is under `%LOCALAPPDATA%\BUSCore\app\app.db`; demo data is in `app_demo.db`. Encrypted exports are under `%LOCALAPPDATA%\BUSCore\exports`.
 
-- Product: the inventory item you build or sell.
-- Recipe: the list of materials or components needed to make a product.
-- Output Product: the product a recipe adds to stock when manufactured.
-- Stock Out: reducing inventory for a sale, loss, theft, or correction.
+In the default Docker setup, the database is `/data/app.db`. The `/data` directory must be mounted to persistent storage. See [Backup and Restore](Backups-and-Data-Persistence.md) before relying on container recreation or updates.
 
-## Still Not Included
+## 5. Make a Backup
 
-BUS Core still does not include full POS, full accounting, QuickBooks/Wave sync, automatic reorder, full job scheduling, cloud accounts, cloud sync, telemetry, payment links, customer portals, or recurring billing.
+After the first successful workflow, make an encrypted backup export and keep its password somewhere appropriate for your shop. An export you cannot decrypt is not useful.
 
-## If You Are Beta Testing
-
-- Read the [Beta Testing Guide](Beta-Testing-Guide.md).
-- Report problems in [Bug Reports](Bug-Reports.md).
-- Suggest workflow improvements in [Feature Requests](Feature-Requests.md).
-
-## Scope Note
-
-Keep setup small at first. Add one vendor, one material, one product, one recipe, one manufacturing run, and one sale before expanding the catalog.
+Next: [First Shop Workflow](First-Shop-Workflow.md).