refinement

AGENTS.md

@@ -104,6 +104,9 @@ If implementation changes invalidate those docs, update them in the same change
 - Purchase-order item lookup must only expose inventory items flagged as purchasable
 - Customer-facing and logistics PDFs should continue to use the backend documents module and Puppeteer pipeline
 - The landing experience should remain `Dashboard`, not `Overview`, and should evolve as a modular metric-first operational surface
+- Projects should be treated as a first-class future domain that anchors long-running program execution across CRM, sales, inventory, purchasing, shipping, and planning
+- Manufacturing should remain a separate future domain for work orders, routings, labor, and shop-floor execution
+- Planning should remain the scheduling/visibility layer over projects and manufacturing, not a replacement for either
 
 ## Feature expectations
 
@@ -112,8 +115,8 @@ Near-term priorities are:
 1. Purchase receiving flow and vendor-side operational depth
 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
+4. Projects and program management
+5. Manufacturing execution
 
 When adding new modules, preserve the ability to extend the system without refactoring the existing app shell.
 

INSTRUCTIONS.md

@@ -29,6 +29,8 @@ This repository implements the platform foundation milestone:
 8. Maintain the denser UI baseline on active screens; avoid reintroducing oversized `px-4 py-3` style controls, tall action bars, or overly loose card spacing without a specific reason.
 9. Treat the landing page as `Dashboard`: a metric-oriented, modular command surface that should accumulate reusable operational panels over time.
 10. Purchase-order item selection must be restricted to inventory items where `isPurchasable = true`.
+11. Treat future `Projects` work as a first-class cross-module domain tying together CRM, sales, inventory, purchasing, shipping, and planning; do not bury it as a one-off manufacturing subfeature.
+12. Keep `Projects`, `Manufacturing`, and `Planning` distinct: projects are long-running program records, manufacturing is execution, and planning is scheduling/visibility.
 
 ## Operational notes
 
@@ -41,11 +43,15 @@ This repository implements the platform foundation milestone:
 - 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.
 - Add future dashboard features as modular metric/action panels instead of one-off hero sections or static marketing-style content.
+- When implementing projects, model the relationships explicitly so project records can anchor execution across customer, order, material, schedule, and shipment workflows.
+- When implementing manufacturing, keep work orders, routings, labor, and shop-floor execution in their own domain rather than collapsing them into projects.
 
 ## Next roadmap candidates
 
 - purchase receiving flow and vendor-side operational depth
 - sales and purchasing document templates
 - shipping labels, bills of lading, and logistics attachments
-- manufacturing gantt scheduling with live project data
+- projects and program management
+- manufacturing execution
+- planning and gantt scheduling with live project/manufacturing data
 - broader audit and operations maturity

README.md

@@ -26,13 +26,19 @@ Current completed foundation areas:
 - shipping foundation
 - branding, attachments, auth/RBAC, and PDF infrastructure
 
+Planned cross-module execution areas:
+
+- projects and program management
+- manufacturing execution
+- planning and gantt scheduling
+
 Near-term priorities:
 
 1. Purchase receiving flow and vendor-facing operational depth
 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
+4. Projects and program management
+5. Manufacturing execution
 
 Revisit / deferred items:
 
@@ -42,6 +48,7 @@ Revisit / deferred items:
 - broader branded PDFs beyond company profile and packing slips
 - inventory transfers, reservations, and deeper stock controls
 - deeper audit-trail coverage
+- projects are not yet first-class records even though planning/manufacturing flows will need them
 
 Dashboard direction:
 
@@ -50,6 +57,34 @@ Dashboard direction:
 - new modules should add reusable dashboard cards/panels instead of replacing the whole layout
 - future additions should emphasize relevant metrics, next actions, alerts, and workflow shortcuts
 - richer recent-activity widgets and exception queues are a planned QOL follow-up, not a separate landing-page redesign
+- projects should eventually feed dashboard widgets for active jobs, overdue milestones, shortages, and shipment readiness
+
+## Projects Direction
+
+Projects should become the long-running program and delivery layer tying together commercial work, engineering context, purchasing, manufacturing, shipping, and customer-facing execution.
+
+Planned interactions:
+
+- CRM: each project should link to a customer account and relevant contacts
+- Sales: quotes and sales orders should be able to spawn or attach to projects
+- Inventory: projects should reference item/BOM scope and later expose shortages or allocations
+- Purchasing: project material demand should be visible to purchasing and receiving workflows
+- Shipping: shipments tied to project deliverables should be visible from the project record
+- Manufacturing: work orders should link back to projects without turning projects into the manufacturing module
+- Planning: project milestones and execution dates should feed gantt scheduling and dependency views
+- Dashboard: projects should contribute status, risk, backlog, and milestone widgets
+
+## Manufacturing Direction
+
+Manufacturing should remain a separate execution subsystem rather than being collapsed into Projects.
+
+Planned interactions:
+
+- Projects: manufacturing orders may belong to a project, but projects remain the higher-level long-running record
+- Inventory: manufacturing consumes components and produces stock
+- Purchasing: shortages and buyout demand should surface from manufacturing execution
+- Shipping: completed manufacturing should feed shipment readiness
+- Planning: manufacturing orders, routings, and work centers should drive capacity and schedule views
 
 ## Workspace
 

ROADMAP.md

@@ -75,18 +75,18 @@ QOL subfeatures:
 
 ### Phase 2: Inventory and manufacturing core
 
-- Item master and SKU structure
-- Warehouse and stock location modeling
-- Inventory transactions and on-hand tracking
-- Bills of materials and custom assemblies
-- Project records tied to manufacturing work
-- File attachments for BOM drawings and manufacturing support docs
+- Item master and SKU structure foundation
+- Warehouse and stock location foundation
+- Inventory transactions and on-hand tracking foundation
+- Bills of materials and custom assemblies foundation
+- File attachments for BOM drawings and manufacturing support docs foundation
 
 QOL subfeatures:
 
+- Item master enrichment: categories, alternate part numbers, revisions, preferred vendor data, and reorder settings
 - Stock transfers between warehouses and locations
 - Reservation and allocation visibility against demand
-- Faster SKU search and keyboard-heavy item/BOM entry flows
+- Faster SKU search and keyboard-heavy item/BOM entry flows refinement
 - 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
@@ -127,7 +127,63 @@ QOL subfeatures:
 - 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
+### Phase 5: Projects and program management
+
+- Project records with customer linkage, status, owner, priority, due dates, and notes
+- Project-to-sales-order and quote linkage so commercial commitments can roll into delivery programs
+- Project document hub for drawings, support files, correspondence, and revision references
+- Milestones, checkpoints, and non-manufacturing work packages for long-running execution tracking
+- Project-level commercial, material, schedule, and delivery rollups
+- Cross-functional visibility for engineering, purchasing, manufacturing, shipping, and customer communication
+
+Module interactions:
+
+- CRM: projects link to customer accounts, reseller-owned end customers, contacts, and account notes
+- Sales: quotes and sales orders can spawn or attach to projects; project status should reflect commercial state where relevant
+- Inventory: projects reference item/BOM scope, expose shortage/reservation pressure, and later roll up material readiness
+- Purchasing: projects surface buyout demand and vendor receipts tied to project material needs
+- Shipping: shipments should be visible from the project record when a project drives deliverables
+- Dashboard: projects add live widgets for active programs, overdue milestones, shortages, and blocked delivery
+- Manufacturing: manufacturing orders and shop execution should link back to projects, but remain their own subsystem
+- Gantt/planning: project milestones and execution dates should feed planning views without collapsing projects into scheduling alone
+
+QOL subfeatures:
+
+- Project templates for repeatable build types
+- Project-specific attachment bundles and revision snapshots
+- One-screen project cockpit with commercial, material, schedule, and shipping summary
+- Better cross-links between project, customer, order, shipment, and inventory records
+- Project filtering by customer, owner, status, due date, and risk
+- Project activity timeline and audit-friendly milestone history
+
+### Phase 6: Manufacturing execution
+
+- Work orders tied to projects, sales demand, or internal build demand
+- Routing/work-center structure for manufacturing steps and handoffs
+- Material issue, consumption, completion, and WIP tracking
+- Labor and machine-time capture for production execution
+- Manufacturing status workflow from release through completion
+- Manufacturing rollups for open work, blockers, shortages, and throughput
+
+Module interactions:
+
+- Projects: manufacturing orders can be attached to projects, but projects remain the higher-level long-running record
+- Inventory: manufacturing consumes components and produces finished/semi-finished stock
+- Purchasing: shortages and buyout demand should be visible from manufacturing execution
+- Shipping: completed manufacturing should feed shipment readiness, but shipping remains separate
+- Dashboard: manufacturing adds live queues for open jobs, blocked work, overdue orders, and completion throughput
+- Planning: manufacturing orders and routings become a major input into capacity and gantt scheduling
+
+QOL subfeatures:
+
+- Traveler/job packet output
+- Partial completions and split-order execution visibility
+- Better shortage and substitute-part handling
+- Shop-floor quick actions and dense tablet-friendly execution views
+- Rework / hold / scrap tracking
+- Work-center dashboards and operator-focused queues
+
+### Phase 7: Planning and scheduling
 
 - Live project-backed SVAR gantt timelines
 - Task dependencies, milestones, and progress updates
@@ -144,7 +200,7 @@ QOL subfeatures:
 - 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
+### Phase 8: Security, audit, and operations maturity
 
 - Expanded role management UI
 - Permission assignment administration
@@ -173,6 +229,8 @@ QOL subfeatures:
 - 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
 - Dashboard cards now use live data, but richer recent-activity widgets and exception queues are still deferred
+- Projects are not yet implemented as first-class long-running program records
+- Manufacturing execution is not yet separated cleanly from planning/scheduling in the current future-state docs and implementation
 
 ## Cross-cutting improvements
 
@@ -188,5 +246,5 @@ QOL subfeatures:
 1. Purchase receiving flow and vendor-side operational depth
 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
+4. Projects and program management
+5. Manufacturing execution

STRUCTURE.md

@@ -22,6 +22,9 @@
 - Purchase-order item pickers must only surface inventory items flagged as purchasable.
 - 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.
+- Treat `projects` as its own long-lived domain under both client and server when implemented; it should integrate with CRM, sales, inventory, purchasing, shipping, and planning rather than living inside only one of those modules.
+- Treat `manufacturing` as a separate long-lived domain from `projects`; work orders, routings, labor capture, WIP, and shop-floor execution should not be modeled only as project fields.
+- Treat `planning` as the scheduling/visibility layer that consumes project and manufacturing data rather than replacing either domain.
 
 ## Backend rules