docu update

AGENTS.md

@@ -17,6 +17,7 @@ MRP Codex is a modular Manufacturing Resource Planning platform intended to be a
 - CRM customers/vendors, hierarchy, contacts, lifecycle metadata, and attachments
 - inventory items, BOMs, warehouses, locations, transactions, item attachments, and item pricing
 - sales quotes and sales orders
+- shipping shipments and packing-slip PDFs
 - Puppeteer PDF foundation
 - single-container Docker deployment
 
@@ -100,14 +101,15 @@ If implementation changes invalidate those docs, update them in the same change
 - Non-filter operational lookups must use searchable pickers/autocomplete instead of long static dropdowns
 - Keep the denser UI baseline on active screens unless a specific workflow needs more space
 - Inventory items maintain both cost and price; sales entry should default from item price
+- Customer-facing and logistics PDFs should continue to use the backend documents module and Puppeteer pipeline
 
 ## Feature expectations
 
 Near-term priorities are:
 
-1. Shipping tied to sales orders
-2. Purchase orders and vendor-side flow
-3. Sales and purchasing PDF templates
+1. Purchase orders and vendor-side flow
+2. Sales and purchasing PDF templates
+3. Shipping labels, bills of lading, and logistics attachments
 4. Live manufacturing gantt scheduling
 5. Audit and operations maturity
 

INSTRUCTIONS.md

@@ -11,6 +11,7 @@ This repository implements the platform foundation milestone:
 - CRM foundation through reseller hierarchy, contacts, attachments, and lifecycle metadata
 - inventory master data, BOM, warehouse, stock-location, transactions, and item attachments
 - sales quotes and sales orders with quick actions and quote conversion
+- shipping shipments linked to sales orders and packing-slip PDFs
 - Dockerized single-container deployment
 - Puppeteer PDF pipeline foundation
 
@@ -34,11 +35,12 @@ This repository implements the platform foundation milestone:
 - Branding defaults live in the frontend theme token layer and are overridden by the persisted company profile.
 - Back up the whole `/app/data` volume to capture both the database and attachments.
 - Treat searchable lookup as a standing UX requirement for inventory, BOM, sales, purchasing, manufacturing, customer, vendor, and other operational record-picking flows. Filter-only controls can still use dropdowns.
+- Extend the existing Puppeteer document pipeline when adding customer-facing or logistics PDFs instead of creating a parallel export mechanism.
 
 ## Next roadmap candidates
 
-- shipping workflows tied to sales orders
 - purchase orders and vendor-facing receiving flow
 - sales and purchasing document templates
+- shipping labels, bills of lading, and logistics attachments
 - manufacturing gantt scheduling with live project data
 - broader audit and operations maturity

README.md

@@ -11,8 +11,36 @@ Current foundation scope includes:
 - CRM contact history, account contacts, and shared attachments
 - inventory item master, BOM, warehouse, stock-location, and stock-transaction flows
 - sales quotes and sales orders with searchable customer and SKU entry
+- shipping shipments linked to sales orders with packing-slip PDFs
 - file storage and PDF rendering
 
+## Product Map
+
+Current completed foundation areas:
+
+- CRM foundation
+- inventory foundation
+- sales foundation
+- shipping foundation
+- branding, attachments, auth/RBAC, and PDF infrastructure
+
+Near-term priorities:
+
+1. Purchase orders and vendor-facing document flow
+2. Sales and purchasing PDF templates
+3. Shipping labels, bills of lading, and logistics attachments
+4. Live manufacturing gantt scheduling
+5. Audit and operations maturity
+
+Revisit / deferred items:
+
+- local Windows Prisma migration reliability
+- frontend code-splitting and bundle-size reduction
+- sales approvals and revision history
+- broader branded PDFs beyond company profile and packing slips
+- inventory transfers, reservations, and deeper stock controls
+- deeper audit-trail coverage
+
 ## Workspace
 
 - `client`: React, Vite, Tailwind frontend
@@ -76,6 +104,12 @@ The current CRM foundation supports:
 - shared file attachments on customer and vendor records
 - commercial terms fields including payment terms, currency, tax exempt, and credit hold
 
+QOL direction:
+
+- saved filters and quick views
+- cleaner hierarchy navigation for reseller/customer trees
+- richer downstream rollups once purchasing and shipping grow further
+
 Recent CRM features depend on the committed Prisma migrations being applied. If you update the code and do not run migrations, the UI may render fields that are not yet present in the database.
 
 ## Inventory
@@ -96,6 +130,13 @@ The current inventory foundation supports:
 - seeded sample inventory items and a starter assembly BOM during bootstrap
 - seeded sample warehouse and stock locations during bootstrap
 
+QOL direction:
+
+- stock transfers
+- reservations and allocations
+- clearer warehouse dashboards and shortage views
+- BOM revisions and where-used visibility
+
 This module introduces `inventory.read` and `inventory.write` permissions. After updating the code, restart the server against the migrated database so bootstrap can upsert the new permissions onto the default administrator role.
 
 `defaultPrice` now flows from inventory items into quote and sales-order line entry when a SKU is selected. Users can still override the line price after selection.
@@ -107,12 +148,41 @@ The current sales foundation supports:
 - quote and sales-order list, detail, create, and edit flows
 - searchable customer lookup instead of static customer dropdowns
 - SKU-searchable line entry for quote and order lines
+- document-level discount, tax, freight, subtotal, and total calculations
+- reseller discount defaulting from customer records into sales documents
 - status quick actions directly from quote and order detail pages
 - quote conversion into a sales order
 - line-level unit prices populated from the selected inventory item default price
 
+QOL direction:
+
+- line duplication and faster keyboard-heavy line editing
+- stronger revision/approval flow
+- richer PDF output for quotes and sales orders
+
 This module introduces `sales.read` and `sales.write` permissions. After updating the code, restart the server against the migrated database so bootstrap can upsert the new permissions onto the default administrator role.
 
+## Shipping
+
+The current shipping foundation supports:
+
+- shipment list, detail, create, and edit flows
+- searchable sales-order lookup instead of a static order dropdown
+- shipment records linked directly to sales orders
+- carrier, service level, tracking number, package count, notes, and ship date fields
+- shipment quick status actions from the shipment detail page
+- related-shipment visibility from the sales-order detail page
+- branded packing-slip PDF rendering from shipment detail pages
+
+QOL direction:
+
+- shipment labels
+- bills of lading
+- logistics attachments and reprint/history actions
+- partial-shipment and split-shipment UX
+
+This module introduces `shipping.read` and `shipping.write` permissions. After updating the code, restart the server against the migrated database so bootstrap can upsert the new permissions onto the default administrator role.
+
 Moving forward, any UI that requires searching for records or items should use a searchable picker/autocomplete rather than a static dropdown. Filter controls can remain dropdowns, but non-filter lookup fields such as SKU pickers, customer selectors, vendor selectors, and similar operational search inputs should not be implemented as long static selects.
 
 ## UI Density
@@ -149,14 +219,18 @@ As of March 14, 2026, the latest committed domain migrations include:
 - inventory transactions and on-hand tracking
 - sales quote and sales-order foundation
 - inventory default price support
+- sales totals and commercial fields
+- shipping foundation
+
+Recent roadmap-driving migrations should always be applied before validating new CRM, inventory, sales, or shipping features in a running environment.
 
 ## UI Notes
 
 - Dark mode persistence is handled through the frontend theme provider and should remain stable across page navigation.
-- The shell layout is tuned for wider desktop use than the original foundation build, and now exposes CRM, inventory, settings, and planning modules from the same app shell.
+- The shell layout is tuned for wider desktop use than the original foundation build, and now exposes CRM, inventory, sales, shipping, settings, and planning modules from the same app shell.
 - The active module screens now follow a tighter density baseline for forms, tables, and detail cards.
 - The client build still emits a Vite chunk-size warning because the app has not been code-split yet.
 
 ## PDF Generation
 
-Puppeteer is used by the backend to render HTML templates into professional PDFs. The Docker image includes Chromium runtime dependencies required for headless execution.
+Puppeteer is used by the backend to render HTML templates into professional PDFs. The current PDF surface includes the branded company-profile preview and shipment packing slips. The Docker image includes Chromium runtime dependencies required for headless execution.

ROADMAP.md

@@ -26,6 +26,10 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni
 - CRM reseller hierarchy, parent-child customer structure, and reseller discount support
 - CRM multi-contact records, commercial terms, lifecycle stages, operational flags, and activity rollups
 - Inventory item master, BOM, warehouse, and stock-location foundation
+- Inventory transactions, on-hand tracking, and item attachments
+- Sales quotes and sales orders with commercial totals logic
+- Shipping shipment records linked to sales orders
+- Packing-slip PDF rendering for shipments
 - SKU-searchable BOM component selection for inventory-scale datasets
 - Theme persistence fixes and denser responsive workspace layouts
 - Full-site density normalization pass across active CRM, inventory, settings, dashboard, and login screens
@@ -39,9 +43,8 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni
 - Prisma migration execution is committed and documented, but local Windows Node 24 schema-engine behavior remains inconsistent; use Node 22 or Docker for migration execution
 - The frontend bundle is functional but should be code-split later, especially around the gantt module
 - CRM reporting is now functional, but broader account-role depth and downstream document rollups can still evolve later
-- Shipping is not yet linked to sales orders
 - Purchasing documents are not yet implemented
-- The current sales foundation does not yet include approvals, revisions, or branded transactional PDFs
+- The current sales/shipping foundation still does not include approvals, revisions, shipment labels, or broader branded transactional PDF coverage beyond packing slips
 
 ## Planned feature phases
 
@@ -51,6 +54,15 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni
 - Additional CRM account-role depth if later sales/purchasing workflows need it
 - More derived CRM rollups once quotes, orders, and purchasing documents exist
 
+QOL subfeatures:
+
+- Saved CRM filters and quick views
+- Better hierarchy navigation between reseller parents and child accounts
+- One-click contact actions for email and phone workflows
+- Duplicate-account detection and merge workflow
+- Cleaner attachment previews and richer record timelines
+- More compact table controls for heavy CRM data-entry users
+
 ### Phase 2: Inventory and manufacturing core
 
 - Item master and SKU structure
@@ -60,6 +72,15 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni
 - Project records tied to manufacturing work
 - File attachments for BOM drawings and manufacturing support docs
 
+QOL subfeatures:
+
+- Stock transfers between warehouses and locations
+- Reservation and allocation visibility against demand
+- Faster SKU search and keyboard-heavy item/BOM entry flows
+- Better warehouse dashboards for on-hand, shortages, and recent movement
+- BOM revision support and clearer where-used visibility
+- Bulk item import/export and mass-update utilities
+
 ### Phase 3: Sales and purchasing documents
 
 - Quotes, sales orders, and purchase orders
@@ -68,6 +89,15 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni
 - Branded PDF templates rendered through Puppeteer
 - Attachments for vendor invoices and supporting documents
 
+QOL subfeatures:
+
+- Line duplication, drag ordering, and keyboard-first line editing
+- Saved customer defaults for tax, freight, and commercial terms
+- Inline stock visibility while building quotes and orders
+- Better totals breakdown visibility on list pages and detail pages
+- Revision comparison view for changed customer-facing documents
+- Faster document cloning and quote-to-order style conversions across document types
+
 ### Phase 4: Shipping and logistics
 
 - Shipment records linked to sales orders
@@ -76,6 +106,15 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni
 - Outbound shipment status workflow
 - Scanned logistics-document attachment handling
 
+QOL subfeatures:
+
+- Shipment labels and printer-friendly document actions
+- Partial shipment workflow and split-shipment visibility
+- Better tracking-link UX and carrier-specific shortcuts
+- Packing verification and ship-confirm checkpoints
+- Shipment search by order, tracking, customer, and carrier from one screen
+- Reprint and history actions for generated logistics PDFs
+
 ### Phase 5: Manufacturing planning and scheduling
 
 - Live project-backed SVAR gantt timelines
@@ -84,6 +123,15 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni
 - Labor and machine scheduling support
 - Theme-compliant gantt customization for light/dark mode
 
+QOL subfeatures:
+
+- Collapsible schedule groupings and saved planner views
+- Drag-and-drop rescheduling improvements
+- Critical-path and overdue highlighting
+- Capacity warnings for overloaded work centers
+- Better mobile and tablet behavior for shop-floor lookups
+- Faster filtering by project, customer, work center, and status
+
 ### Phase 6: Security, audit, and operations maturity
 
 - Expanded role management UI
@@ -92,6 +140,27 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni
 - Backup/restore workflow documentation and scripts
 - Health checks, startup diagnostics, and production readiness cleanup
 
+QOL subfeatures:
+
+- Admin diagnostics screen for permissions, migrations, storage, and PDF health
+- Safer destructive-action confirmations and recovery messaging
+- Better user/session visibility for operational admins
+- More explicit environment validation on startup
+- Log-view and export helpers for support/debugging
+- Backup verification checklist and restore drill guidance
+
+## Revisit / Deferred Items
+
+- Local Windows Prisma migration reliability still needs a cleaner documented workflow or tooling wrapper
+- Frontend bundle splitting is still deferred; the Vite chunk-size warning remains
+- Sales approvals and document revision history were planned but not yet built
+- Broader branded PDFs for quotes and sales orders still need to be added
+- Shipping is now linked to sales orders, but labels, bills of lading, and logistics attachments are still pending
+- Inventory transactions exist, but transfers, reservations, and more advanced stock controls still need follow-up
+- CRM document rollups and broader account-role depth were deferred until more downstream modules exist
+- Audit-trail depth is still thin outside the current record/update flows
+- Some generated document and workflow screens still need additional polish for dense, keyboard-efficient operational use
+
 ## Cross-cutting improvements
 
 - Stronger validation and error reporting across all APIs
@@ -103,8 +172,8 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni
 
 ## Near-term priority order
 
-1. Shipping module tied to sales orders
-2. Purchase orders and vendor-facing document flow
-3. Sales and purchasing PDF templates
+1. Purchase orders and vendor-facing document flow
+2. Sales and purchasing PDF templates
+3. Shipping labels, bills of lading, and logistics attachments
 4. Live manufacturing gantt scheduling
 5. Broader audit and operations maturity

STRUCTURE.md

@@ -17,6 +17,7 @@
 - PDF screen components must remain separate from API-rendered document templates.
 - Any non-filter lookup UI must be implemented as a searchable picker or autocomplete; do not use long static dropdowns for operational datasets such as items, customers, vendors, or document-linked records.
 - Inventory items expose both cost and sell price. Downstream sales document entry should default from the item price field rather than requiring duplicate price maintenance.
+- Shipping, sales, and future purchasing PDFs should be rendered through the backend documents module and shared Puppeteer pipeline rather than ad hoc frontend-only exports.
 - Preserve the current dense operations UI style on active module pages: compact controls, tighter card padding, and shorter empty states unless a screen has a clear reason to be more spacious.
 
 ## Backend rules

UNRAID.md

@@ -125,7 +125,7 @@ When you publish a new image:
 
 Because MRP Codex runs `prisma migrate deploy` during startup, committed migrations are applied automatically before the app launches.
 
-This is especially important now that recent releases added CRM expansion, inventory transactions, sales documents, and the inventory `defaultPrice` field. Let the container complete startup migrations before testing new screens.
+This is especially important now that recent releases added CRM expansion, inventory transactions, sales documents, shipping, packing slips, and the inventory `defaultPrice` field. Let the container complete startup migrations before testing new screens.
 
 ## Backup guidance