The Work Package Suite turns a project's standard procedure into release-ready Installation Work Packages (IWPs). You work in three stages, always in the same order:
Pick or create a Project on the home page. Each project keeps its own SOP and its own Work Packages, so you can run many jobs at once.
SOP Configuration — set the project baseline in 10 steps (team, sign-offs, WP types, governance & sizing, quality, platforms, sequence, constraints, sources). Every Work Package inherits these defaults. The Creator stays locked until the SOP is marked complete.
Work Package Creation — author individual IWPs against the SOP, clear their constraints, and issue them to the field.
Dashboard — track status, hours, due dates, and what's gating each package across the project.
Moving around
From the home page, open SOP Configuration, the Work Package Creator, or the Dashboard. Inside the suite, switch any time using the top tabs: ⚙️ SOP Configuration, 📋 Work Package Creation, and 📊 Dashboard. The active project and SOP follow you across all of them.
New here? On the home page choose the Sample Project, then click ⭐ Load Sample in the suite to see a fully filled-out SOP and an example Work Package.
` },
{ id: 'projects', title: 'Projects', body: `
Projects
A project is the top-level container — every SOP and Work Package belongs to one. Create or select projects on the home page.
Project fields
Project Name (required)
Project Number
Client
Division / Sector
Site / Location
The active project
The active project is the one you're currently working in. All SOP and Work Package data is scoped (namespaced) to it, so switching projects loads that project's own configuration and packages — nothing leaks between jobs. Use the change link next to the active project name to switch.
Projects are stored centrally via the API and mirrored to your browser, so the suite still works offline; it re-syncs when the connection returns.
The SOP is the project baseline. Walk the 10 steps with ← Back / Next →, or jump using the step indicators. The final step is ✓ SOP Complete — saving it unlocks the Work Package Creator and turns the home-page card green.
Project Basics — name, number, client, division/sector, site. Inherited by every WP.
Project Team Leadership — PM, APM, CM, QM, plus any additional members (+ Add Team Member).
Required Sign-Off Roles — Superintendent and Foreman are always required; add optional roles (HSE, Quality Rep, Planner, etc.) with + Add Role.
Work Package Types — enable the install types this project uses (Conduit Install, Wire Pull, Terminations, …). Enabled types populate the WP type picker.
Governance & WP Numbering — the WP number format (e.g. WP##-[Sector]-[TYPE]), issuance strategy, the project's disciplines, the discipline strategy, and WP sizing (see Sizing and Disciplines).
Tracking & Commissioning Platforms — e.g. CxAlloy, Procore, ACC.
Construction Sequence — the install flow; reorder by dragging (⠿), edit labels, add ◆ QC Hold gates or custom steps. These feed the WP "predecessor" picker.
Release Gate Constraints — choose which standard AWP constraints apply and add custom ones (see Constraints).
Engineering Sources & References — labelled links (Design Drawings, Specs, …) that appear as quick-access buttons in the WP Creator's Drawings & Attachments.
Fields a WP inherits from the SOP show a "from SOP" tag and are locked. You can override a locked field with 🔒 Edit, which requires a logged reason.
` },
{ id: 'wps', title: 'Work Packages', body: `
Creating Work Packages
In the Creator, start a package with + New (blank, auto-numbered) or ⧉ Duplicate (copies a saved package and increments the number). The WP Number is built automatically from the SOP number format plus your scope fields, the WP type, and a counter — it's read-only.
Key fields
Subject / Title (required) and WP Type (required, from the SOP).
Assets — link each controls.dev asset the package covers.
Quality / Hold Points, Approvals & Sign-offs, and Closeout (actual hours, as-builts, lessons learned — shown at QC/Closed).
Saving
Save Draft stores the package; ⚡ Save & View saves and renders the print-ready output. Drafts auto-save to your browser as you type, so nothing is lost if you close the tab.
` },
{ id: 'statuses', title: 'Statuses', body: `
Work Package statuses
Status
Meaning
Draft
Work in progress; not yet released.
Scheduled
Planned and scheduled; upcoming.
Issued
Released to the field. Requires all constraints Cleared or N/A.
In Progress
Actively being worked.
QC
In quality check / inspection.
Closed
Completed.
Issue (Hold)
A constraint reopened after release — work is paused until it's resolved.
A package cannot move to Issued while any constraint is Open. If a constraint reopens after a package is Issued, its status automatically drops to Issue (Hold) and the suite makes you log what happened.
On a multi-discipline package, each discipline carries its own status and the overall status rolls up to the least-advanced discipline — so a package is never "Closed" while one trade still lags.
Constraints are the readiness checklist that gates a package's release to the field. They follow Advanced Work Packaging (AWP Vol II §2.3.2). The standard set:
Safety & Permitting
Quality Control / Inspection
IFC Drawings & Specs
Schedule
Materials (on site, bagged & tagged)
Prefabrication
Work Access & Laydown
Craft Availability
Construction Equipment & Tools
Scaffolding / Access Equipment
Pick which apply (and add custom ones) in SOP Step 9. Each constraint on a package has one of three states:
State
Effect
Open
Not yet cleared — blocks release.
Cleared
Requirement met — counts toward release-ready.
N/A
Not applicable to this package — counts as cleared.
The release gate
A package is release-ready when every constraint is Cleared or N/A. The sticky banner shows green when ready, amber when constraints are still open, and red when on hold.
When the last open constraint clears, the suite offers to mark the package Issued.
If a constraint reopens after the package is Issued, you log the hold (what reopened, details, optional doc link & photo) and the status drops to Issue (Hold).
Disciplines are trades (Mechanical, Electrical, Tech, …) set in SOP Step 5. The discipline strategy controls how packages handle them:
Let the planner choose per package (recommended) — pick one discipline (flat scope) or several (per-discipline scope + the Split option).
One discipline per package — each WP is single-discipline.
Multiple disciplines per package — scope is always split by discipline.
Split by Discipline
When a package covers 2+ disciplines, the ⎘ Split by Discipline button breaks it into one numbered instance per discipline — WP01A, WP01B, WP01C (or _MECH/_ELEC suffixes, set in the SOP). The original is kept as a master / roll-up; each instance:
becomes its own single-discipline package, issued independently;
receives only the scope steps and materials tagged to that discipline;
stays linked back to the master.
Tag material rows to a discipline before splitting. Untagged rows stay on the master only and won't be routed to any instance. Masters are excluded from dashboard counts so hours aren't double-counted.
` },
{ id: 'sizing', title: 'Sizing', body: `
Work Package sizing
In SOP Step 5 you set a typical WP size band, which sets a split threshold (max labor hours):
Size band
Split threshold
Small — 1–2 days (≈8–24 hrs)
24 hrs
Standard — 3–5 days (≈40–80 hrs)
80 hrs
Large — 1–2 weeks (≈80–160 hrs)
160 hrs
Custom…
you set it
In the Creator, the Est. Hrs. field is checked live against the threshold. Within range you see the target band; over it you get an amber warning — "⚠ … exceeds the …-hr split threshold — consider breaking this package down" — and a nudge to split by discipline where that applies. It's a guide, not a hard block: you can proceed if it's intentional.
The dashboard aggregates every (non-master) package in the active project. Open it from the home page, the suite's 📊 Dashboard tab, or the Creator header.
Metric cards (click to filter)
Total WPs, Release-ready, On hold, Overdue
Est. hrs and Actual hrs (summed)
Breakdowns & gates
By status and by discipline chips.
⛔ Gating constraints — lists every blocked package and exactly which constraints are holding it.
The table
Shows WP #, subject, type, discipline, status, Gates (clear, n open, or master), due date (red if overdue), and hours. Row actions: issue (when release-ready), view, and edit. Filter with the search box and the status / discipline dropdowns.
Split masters are labelled and excluded from the counts; you issue their instances one at a time as each becomes release-ready.
⭐ Load Sample is context-aware: on the SOP tab it loads a complete sample SOP; on the WP tab it loads an example Work Package. Great for learning the tool or demoing.
Import / Export
Work Packages — ⤓ Export (JSON) downloads all saved packages; import restores them.
SOP — the Creator can import a SOP .json (via ⤒ Import SOP) or load the sample SOP.
Materials — import a bill of materials from Excel/CSV, or download a template.
Comments & feedback
Leave feedback from the home page, per-step comments in the SOP tool (💬 Step Comments), or package comments in the Creator's 💬 Comments drawer. Comments are saved and can be exported/imported as .json so reviewers can share them — and, when the API is reachable, they're collected centrally too.
Usage logs
📊 Usage Logs / ▤ Usage Data shows session and event counts and can export the full log. A dev-mode toggle pauses tracking during demos.
Enter in a sequence, constraint, or material input adds/saves that row.
Esc closes any modal — this help center, comments, the constraint library, and the hold-log dialog.
Hover any i icon for an inline hint.
Data is kept per project — switch projects from the home page.
Your work auto-saves to the browser as you type; Save & View produces the print-ready output.
Click a metric card or status chip on the Dashboard to filter the table.
` },
{ id: 'glossary', title: 'Glossary', body: `
Glossary
Term
Meaning
IWP
Installation Work Package — the field-level package this tool produces.
AWP
Advanced Work Packaging — the methodology behind the constraint set and release gate.
SOP
Standard Operating Procedure — the project baseline every WP inherits.
Constraint
A readiness item (Open / Cleared / N/A) that gates release.
Release-ready
All constraints Cleared or N/A — the package can be Issued.
Issued
Released to the field.
Issue (Hold)
A released package paused because a constraint reopened.
Discipline
A trade (Mechanical, Electrical, Tech, …).
Split / Master / Instance
Breaking a multi-discipline package (master/roll-up) into single-discipline instances (WP01A/B/C).
Scope
The sequenced steps the crew performs.
Sequence
SOP-defined construction phases; a WP can name a predecessor step.
Bagged & tagged
Materials on site, kitted, and labelled — part of the Materials constraint.
MIMO
Material In / Material Out — kitting and staging logistics.
Asset
A controls.dev record (equipment/system) a package is built around.
Hold / Witness point
Hold = work stops until inspection sign-off; Witness = inspection offered but work may proceed.
Active project
The currently selected project; all data is scoped to it.
` },
{ id: 'faq', title: 'FAQ', body: `
Frequently asked questions
The Work Package Creator is locked — why?
The SOP for the active project isn't complete yet. Finish SOP Configuration and click ✓ SOP Complete on the last step; the Creator unlocks and the home card turns green.
Why can't I set a package to Issued?
At least one constraint is still Open. Clear or mark N/A every constraint — the release banner turns green — and the suite will offer to issue it.
My package's materials didn't all carry over when I split it.
Only material rows tagged to a discipline are routed to that instance. Untagged rows stay on the master. Tag them before splitting.
Why don't split masters show in the dashboard totals?
Masters are roll-ups; counting them would double-count their hours and packages. The individual instances are counted instead.
Will I lose my work if I close the browser?
No — drafts auto-save locally per project and reload next time. Use Export (JSON) for a backup or to share with a teammate.
Does each project keep its own data?
Yes. SOP and Work Packages are scoped to the active project; switching projects loads that project's own set.
How do I report a problem or suggestion?
Use the feedback / comments features (home page, SOP Step Comments, or the Creator's Comments drawer).
` }
];
// ── build ─────────────────────────────────────────────────────────────────
function buildModal() {
if (document.getElementById('ui-help-overlay')) return;
var overlay = document.createElement('div');
overlay.className = 'ui-help-overlay';
overlay.id = 'ui-help-overlay';
var nav = TOPICS.map(function (t) {
return '' + t.title + '';
}).join('');
var sections = TOPICS.map(function (t) {
return '' + t.body + '';
}).join('');
overlay.innerHTML =
'
' +
'
' +
'Help — Work Package Suite' +
'' +
'' +
'
' +
'
' +
'' +
'
' +
'
No matches. Try another word.
' +
sections +
'
' +
'
' +
'
';
overlay.addEventListener('click', function (e) { if (e.target === overlay) closeHelp(); });
document.body.appendChild(overlay);
// nav clicks + in-content cross-links jump to a section
overlay.addEventListener('click', function (e) {
var t = e.target.closest('[data-help-target],[data-help-jump]');
if (!t) return;
e.preventDefault();
jumpTo(t.getAttribute('data-help-target') || t.getAttribute('data-help-jump'));
});
// search
var q = overlay.querySelector('#ui-help-q');
q.addEventListener('input', function () { runSearch(q.value); });
// highlight nav as you scroll
var content = overlay.querySelector('#ui-help-content');
content.addEventListener('scroll', syncActiveNav, { passive: true });
}
function jumpTo(id) {
var sec = document.getElementById('ui-help-sec-' + id);
if (!sec) return;
// Clear any active search filter so the target is visible.
var q = document.getElementById('ui-help-q');
if (q && q.value) { q.value = ''; runSearch(''); }
sec.scrollIntoView({ block: 'start' });
setActiveNav(id);
}
function setActiveNav(id) {
var nav = document.getElementById('ui-help-nav');
if (!nav) return;
nav.querySelectorAll('a').forEach(function (a) {
a.classList.toggle('active', a.getAttribute('data-help-target') === id);
});
}
function syncActiveNav() {
var content = document.getElementById('ui-help-content');
if (!content) return;
var top = content.scrollTop, best = null, bestDist = Infinity;
TOPICS.forEach(function (t) {
var sec = document.getElementById('ui-help-sec-' + t.id);
if (!sec || sec.classList.contains('hide')) return;
var d = Math.abs(sec.offsetTop - top);
if (sec.offsetTop - top <= 40 && d < bestDist) { bestDist = d; best = t.id; }
});
if (best) setActiveNav(best);
}
// ── search: filter sections + highlight matches ───────────────────────────
function clearMarks(root) {
root.querySelectorAll('mark').forEach(function (m) {
var txt = document.createTextNode(m.textContent);
m.parentNode.replaceChild(txt, m);
});
root.normalize();
}
function markMatches(el, query) {
var lower = query.toLowerCase();
var walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT, {
acceptNode: function (node) {
if (!node.nodeValue.trim()) return NodeFilter.FILTER_REJECT;
var p = node.parentNode.nodeName;
if (p === 'MARK' || p === 'STYLE' || p === 'SCRIPT') return NodeFilter.FILTER_REJECT;
return node.nodeValue.toLowerCase().indexOf(lower) >= 0 ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT;
}
});
var nodes = [], n;
while ((n = walker.nextNode())) nodes.push(n);
nodes.forEach(function (node) {
var val = node.nodeValue, low = val.toLowerCase(), frag = document.createDocumentFragment(), i = 0, idx;
while ((idx = low.indexOf(lower, i)) >= 0) {
if (idx > i) frag.appendChild(document.createTextNode(val.slice(i, idx)));
var mk = document.createElement('mark');
mk.textContent = val.slice(idx, idx + query.length);
frag.appendChild(mk);
i = idx + query.length;
}
if (i < val.length) frag.appendChild(document.createTextNode(val.slice(i)));
node.parentNode.replaceChild(frag, node);
});
}
function runSearch(query) {
var content = document.getElementById('ui-help-content');
var nav = document.getElementById('ui-help-nav');
var noresult = document.getElementById('ui-help-noresult');
if (!content) return;
query = (query || '').trim();
var hits = 0;
TOPICS.forEach(function (t) {
var sec = document.getElementById('ui-help-sec-' + t.id);
var navItem = nav.querySelector('[data-help-target="' + t.id + '"]');
clearMarks(sec);
var match = !query || sec.textContent.toLowerCase().indexOf(query.toLowerCase()) >= 0;
sec.classList.toggle('hide', !match);
if (navItem) navItem.classList.toggle('nohit', !!query && !match);
if (match) {
hits++;
if (query) markMatches(sec, query);
}
});
noresult.style.display = (query && hits === 0) ? 'block' : 'none';
if (query) { content.scrollTop = 0; }
else { syncActiveNav(); }
}
// ── public API ──────────────────────────────────────────────────────────────
global.openHelp = function (topicId) {
buildModal();
document.getElementById('ui-help-overlay').classList.add('open');
var q = document.getElementById('ui-help-q');
if (topicId && typeof topicId === 'string') jumpTo(topicId);
else { setActiveNav(TOPICS[0].id); if (q) setTimeout(function () { q.focus(); }, 30); }
};
global.closeHelp = function () {
var o = document.getElementById('ui-help-overlay');
if (o) o.classList.remove('open');
};
document.addEventListener('keydown', function (e) {
if (e.key === 'Escape') global.closeHelp();
});
// ── floating launcher on pages without their own Help button ────────────────
function maybeAddFab() {
var inIframe = (function () { try { return window.top !== window.self; } catch (e) { return true; } })();
if (inIframe || global.WP_HELP_NO_FAB) return; // suite shows the parent's button
if (document.querySelector('[onclick*="openHelp"]')) return; // page already has a Help trigger
if (document.getElementById('ui-help-fab')) return;
var b = document.createElement('button');
b.id = 'ui-help-fab'; b.className = 'ui-help-fab'; b.type = 'button';
b.title = 'Help'; b.setAttribute('aria-label', 'Open help'); b.textContent = '?';
b.addEventListener('click', function () { global.openHelp(); });
document.body.appendChild(b);
}
if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', maybeAddFab);
else maybeAddFab();
})(window);