@sparkerp/plugin-sdk 0.1.0 → 1.1.0

package/bundle/docs/applications/hcm/assets-maintenance.md

@@ -0,0 +1,25 @@
+---
+title: Asset Maintenance
+audience: tenant
+---
+
+# Asset Maintenance (HCM)
+
+This page documents the shipped **Asset Maintenance** screen
+(`hcm-assets`). Not for plugin developers.
+
+## Creating a work order
+
+**New Maintenance** — pick the Asset, a Maintenance Type, Priority, a
+Problem summary and Work Description, an assigned Technician (or external
+Vendor), Scheduled Start/End, and an Estimated/Actual Cost. Each work
+order gets a real Work Order Number for tracking.
+
+## Tracking work
+
+The grid shows Asset, Type, Priority, Technician, and Status for every
+work order. KPIs: Scheduled, In Progress, Completed.
+
+## Related
+
+- [Asset Inventory & Asset Categories](./assets-inventory.md)

package/bundle/docs/applications/hcm/assets-software-licenses.md

@@ -0,0 +1,27 @@
+---
+title: Software Licenses
+audience: tenant
+---
+
+# Software Licenses (HCM)
+
+This page documents the shipped **Software Licenses** screen
+(`hcm-assets`) — tracking software entitlements, separate from physical
+Asset Inventory. Not for plugin developers.
+
+## Creating a license record
+
+**New Software License** — Product Name, Publisher, License Number,
+License Type, and **License Model** (e.g. per-seat, per-device,
+subscription). Set the **Entitlement Quantity** (how many seats/uses
+you've purchased), Start Date and Expiry Date, and the Cost/Currency.
+
+## Tracking usage
+
+The grid shows Product, Publisher, License Model, Entitlement, and
+Expiry, alongside Status. KPIs: Total Products, Active, Expired — a quick
+way to spot licenses that have lapsed and need renewal.
+
+## Related
+
+- [Asset Inventory & Asset Categories](./assets-inventory.md)

package/bundle/docs/applications/hcm/attendance-core.md

@@ -0,0 +1,46 @@
+---
+title: Attendance — Dashboard, Daily Attendance, Register, Biometric & Devices
+audience: tenant
+---
+
+# Attendance — Dashboard, Daily Attendance, Register, Biometric & Devices (HCM)
+
+This page documents the operational core of the shipped **Time &
+Attendance** module (`hcm-attendance`). Not for plugin developers.
+
+**Who this is for:** HR/attendance admins day to day; managers checking
+their team.
+
+## Attendance Dashboard
+
+A real-time overview — every KPI card here is a genuine live count (not a
+sample), covering who's present, absent, late, on leave, and similar,
+right now.
+
+## Daily Attendance
+
+The main operational screen: process and review attendance day by day, per
+employee — punch times, computed hours, and exceptions.
+
+## Attendance Register
+
+A consolidated view across a date range (rather than one day at a time) —
+the same underlying attendance/punch/exception/regularization data as
+Daily Attendance, laid out for reviewing a period at once.
+
+## Biometric Attendance
+
+The raw feed from biometric devices — punch transactions as they come in,
+and their processing/sync status.
+
+## Device Management
+
+Manage the physical attendance-capture devices themselves, and which
+employees are enrolled on which device.
+
+## Related
+
+- [Late & Early, Overtime & Regularization](./attendance-exceptions.md)
+- [Field Work & Work From Home](./attendance-location.md)
+- [Attendance Policies](./attendance-policies.md)
+- [Attendance Reports](./attendance-reports.md)

package/bundle/docs/applications/hcm/attendance-exceptions.md

@@ -0,0 +1,33 @@
+---
+title: Late & Early Records, Overtime & Regularization
+audience: tenant
+---
+
+# Late & Early Records, Overtime & Regularization (HCM)
+
+This page documents three shipped **attendance exception** screens
+(`hcm-attendance`) — the "something wasn't a normal on-time day" cases.
+Not for plugin developers.
+
+## Late & Early Records
+
+Every detected late-arrival or early-departure, with severity, how many
+minutes it's chargeable for, whether it's been regularized, and whether it
+affects payroll.
+
+## Overtime
+
+Overtime records — type, rate, and approval status — checked against
+whatever overtime policy applies to that employee. Submitting overtime
+routes through an approval workflow.
+
+## Regularization
+
+Where an employee (or their manager, on their behalf) corrects an
+attendance mistake — a missed punch, a wrong time — as a numbered,
+trackable request that goes through approval rather than editing the
+attendance record directly.
+
+## Related
+
+- [Attendance — Dashboard, Daily Attendance, Register, Biometric & Devices](./attendance-core.md)

package/bundle/docs/applications/hcm/attendance-location.md

@@ -0,0 +1,25 @@
+---
+title: Field Work & Work From Home
+audience: tenant
+---
+
+# Field Work & Work From Home (HCM)
+
+This page documents two shipped **where you're working** screens
+(`hcm-attendance`) — for when an employee isn't at the regular office. Not
+for plugin developers.
+
+## Field Work
+
+Client/site visit assignments — including a multi-stop sequence for a
+single day, when an employee visits more than one location.
+
+## Work From Home
+
+WFH requests, broken down day by day (a request can cover multiple days,
+each tracked individually). Submitting a WFH request routes through an
+approval workflow.
+
+## Related
+
+- [Attendance — Dashboard, Daily Attendance, Register, Biometric & Devices](./attendance-core.md)

package/bundle/docs/applications/hcm/attendance-policies.md

@@ -0,0 +1,23 @@
+---
+title: Attendance Policies
+audience: tenant
+---
+
+# Attendance Policies (HCM)
+
+This page documents the shipped **Attendance Policies** screen
+(`hcm-attendance`) — the rules attendance is measured against. Not for
+plugin developers.
+
+**Who this is for:** HR/attendance admins setting up rules, usually once.
+
+## What you configure
+
+Tenant-configurable attendance rules — grace periods, working hours,
+late/early thresholds and similar — plus which employees or groups each
+policy applies to (its "scope"). Changing a policy routes through an
+approval workflow rather than applying immediately.
+
+## Related
+
+- [Late & Early Records, Overtime & Regularization](./attendance-exceptions.md)

package/bundle/docs/applications/hcm/attendance-reports.md

@@ -0,0 +1,20 @@
+---
+title: Attendance Reports
+audience: tenant
+---
+
+# Attendance Reports (HCM)
+
+This page documents the shipped **Attendance Reports** screen
+(`hcm-attendance`) — the reporting hub for everything else in the
+Attendance module. Not for plugin developers.
+
+## What you see
+
+An **Attendance Summary** of real, live counts, plus a report hub
+organized by category — pick the kind of report you want (e.g. exceptions,
+overtime, regularization) and it takes you to that specific report.
+
+## Related
+
+- [Attendance — Dashboard, Daily Attendance, Register, Biometric & Devices](./attendance-core.md)

package/bundle/docs/applications/hcm/benefits-allowances.md

@@ -0,0 +1,39 @@
+---
+title: Allowances (Benefits)
+audience: tenant
+---
+
+# Allowances (Benefits) (HCM)
+
+This page documents the shipped **Allowances** screen inside the
+**Benefits** module (`hcm-benefits`). Not for plugin developers.
+
+> **Note:** there's a separate, differently-scoped Allowances screen inside
+> the [Compensation module](./compensation-allowances-benefits.md) too —
+> that one is about per-employee allowance assignments with a calculated
+> amount. This one is about the admin-configured allowance *definitions*
+> themselves, plus which employees they're assigned to. If you're looking
+> for the wrong one, check the other module.
+
+## Two grids, one screen
+
+### Allowance definitions
+
+**New Allowance** — Allowance Name, Allowance Code, Allowance Type,
+Category, Amount, Currency, Frequency, **Proration Enabled** (whether a
+partial period gets a prorated amount rather than the full amount), and
+Effective/Expiry dates. New definitions start Draft → **Submit** →
+**Approve** → **Activate**; once active you can **Suspend** or
+**Terminate**.
+
+### Employee assignments
+
+**Assign Allowance** — pick the Employee and the Allowance definition,
+then either a fixed **Amount** or a **Percentage**, the **Frequency**, an
+**Assignment Source** (why they're getting it), a **Reason**, and
+Effective/Expiry dates. Same submit → approve → activate lifecycle as
+definitions, tracked separately (Total, Draft, Pending Approval, Active).
+
+## Related
+
+- [Benefit Plans, Health Benefits, Insurance & Retirement Benefits](./benefits-plans.md)

package/bundle/docs/applications/hcm/benefits-analytics.md

@@ -0,0 +1,25 @@
+---
+title: Benefits Dashboard & Reports
+audience: tenant
+---
+
+# Benefits Dashboard & Reports (HCM)
+
+This page documents two shipped **Benefits** analytics screens
+(`hcm-benefits`). Not for plugin developers.
+
+## Benefits Dashboard
+
+9 real KPI tiles: Active Benefit Plans, Active Health Plans, Active
+Insurance Policies, Active Retirement Plans, Active Enrollments, Pending
+Claims, Pending Reimbursements, Active Allowances, and Avg Plan
+Utilization — a single view across every Benefits screen, useful for
+spotting a backlog of pending claims/reimbursements before it grows.
+
+## Benefits Reports
+
+A tabular, exportable reporting view over the same real Benefits data.
+
+## Related
+
+- [Benefit Plans, Health Benefits, Insurance & Retirement Benefits](./benefits-plans.md)

package/bundle/docs/applications/hcm/benefits-employee-processes.md

@@ -0,0 +1,44 @@
+---
+title: Employee Enrollment, Benefit Claims & Reimbursements
+audience: tenant
+---
+
+# Employee Enrollment, Benefit Claims & Reimbursements (HCM)
+
+This page documents three shipped **Benefits** process screens
+(`hcm-benefits`) — what actually happens for an employee, day to day. Not
+for plugin developers.
+
+## Employee Benefit Enrollment
+
+Enroll an employee in a benefit plan: pick the plan and **Coverage Type**,
+**Enrollment Type** (e.g. new hire, open enrollment, life event), and set
+Dependent Count / Beneficiary Count if the plan covers them. Employer and
+Employee Contribution amounts (and the Total Contribution) are tracked per
+enrollment, along with an optional **Waiver Reason** if someone opts out
+of an otherwise-eligible benefit. The lifecycle: **submit → approve →
+activate → terminate**, tracked via the KPI row (Total, Draft, Pending
+Approval, Active).
+
+## Benefit Claims
+
+Submit a claim against an enrolled benefit: **Claim Type**, **Service
+Date**, **Claim Amount**, and a **Provider Reference**. As it's reviewed,
+the record fills in **Eligible Amount**, **Approved Amount**,
+**Employer/Employee Share**, and finally **Settlement Amount** — so you
+can see exactly how much of what you claimed was actually approved and
+paid, not just an approve/reject flag. Same submit → approve → settle
+lifecycle, tracked in the KPI row.
+
+## Reimbursements
+
+General expense claims that aren't tied to any specific benefit
+enrollment — pick a **Category**, describe the **Business Purpose**, and
+track **Total Claim Amount** against **Total Approved Amount** (and
+**Total Rejected Amount**, if part of it was denied). These go through a
+Manager → HR → Finance approval chain, with a separate **Payment Status**
+once approved, so you can tell "approved" apart from "actually paid."
+
+## Related
+
+- [Benefit Plans, Health Benefits, Insurance & Retirement Benefits](./benefits-plans.md)

package/bundle/docs/applications/hcm/benefits-plans.md

@@ -0,0 +1,60 @@
+---
+title: Benefit Plans, Health Benefits, Insurance & Retirement Benefits
+audience: tenant
+---
+
+# Benefit Plans, Health Benefits, Insurance & Retirement Benefits (HCM)
+
+This page documents four shipped **Benefits** screens (`hcm-benefits`)
+covering the plans/policies your company offers. Not for plugin
+developers.
+
+## Benefit Plans
+
+The master catalog across every category: Health, Dental, Vision, Life
+Insurance, Disability, Accident, Retirement, Wellness, Meal,
+Transportation, Flexible Benefits, Paid Time Off, Employee Assistance, or
+Other.
+
+**Add Benefit Plan** is organized into three sections:
+
+- **Basic Information** — Plan Name, Plan Code, Category, Plan Type,
+  Provider, Description.
+- **Coverage & Contribution** — Coverage Type (Employee Only / + Spouse /
+  + Children / + Family / Custom), Contribution Method (Fixed Amount /
+  Percentage / Tiered / Age Based / Salary Based / Coverage Based /
+  Custom Formula), Employer Contribution, Employee Contribution, Currency.
+- **Dates & Ownership** — Effective Date, Expiry Date, Renewal Date,
+  Benefits Owner.
+
+A new plan starts as **Draft**. From the detail view: **Submit for
+Approval**, then once approved, **Activate**. From there you can
+**Suspend** it (temporarily pause new enrollment) or **Archive** it. The
+KPI row (Total Plans, Active Plans, Draft Plans, Total Enrolled) and the
+grid's Enrollment % column tell you how much uptake each plan is actually
+getting.
+
+## Health Benefits
+
+The same shape, specifically for employer-sponsored medical/dental/vision
+plans — Plan Type, Provider, Premium, and Enrollment %. The KPI row here
+swaps in **Total Monthly Premium** (real cost across active plans) instead
+of a plain active count, since tracking premium cost is the point of this
+screen.
+
+## Insurance
+
+Life/accident/disability/critical-illness/travel policies — Policy Code,
+Insurance Type, Provider, Coverage Amount, Enrollment %, and Policy
+Administrator. KPIs: Active Policies, Draft Policies, Insured Employees.
+
+## Retirement Benefits
+
+Provident fund/pension/superannuation/defined-contribution plans — Plan
+Type, Provider, **Combined Contribution %** (employer + employee
+combined), Enrollment %, Plan Administrator. KPIs: Active Retirement
+Plans, Draft Plans, Enrolled Employees.
+
+## Related
+
+- [Employee Enrollment, Benefit Claims & Reimbursements](./benefits-employee-processes.md)

package/bundle/docs/applications/hcm/communications-announcements.md

@@ -0,0 +1,31 @@
+---
+title: Announcements & Employee Communications
+audience: tenant
+---
+
+# Announcements & Employee Communications (HCM)
+
+This page documents two shipped **Communications** screens
+(`hcm-communications`). Not for plugin developers.
+
+## Announcements
+
+Real lifecycle: draft → **Submit for Review** → **Approve** →
+**Publish** → **Archive**. Set a Category, Priority, Owner, and Publish
+At date. Once published, the grid tracks real **View Count** and
+**Acknowledged Count**, so you can see whether an announcement is
+actually being read, not just that it went out. KPIs: Drafts, Pending
+Approval, Scheduled, Published.
+
+## Employee Communications
+
+A two-way inbox between HR and employees. Each thread tracks the
+Employee, Subject, Category, Priority, who it's **Assigned To**, when the
+**Last Message** was sent, and Status — moving through Open →
+(optionally) Escalated → Resolved. KPIs: Unread, Open, Escalated,
+Resolved — so HR can see at a glance if anything's sitting unanswered.
+
+## Related
+
+- [Notifications](./communications-notifications.md)
+- [Communication History](./communications-history.md)

package/bundle/docs/applications/hcm/communications-history.md

@@ -0,0 +1,23 @@
+---
+title: Communication History
+audience: tenant
+---
+
+# Communication History (HCM)
+
+This page documents the shipped **Communication History** screen
+(`hcm-communications`) — a unified, searchable, read-only timeline across
+every channel. Not for plugin developers.
+
+## What it does
+
+Search and browse everything sent — email, SMS, push, in-app, and
+announcements — in one timeline, each entry showing its Recipient,
+Subject, Type, Source (which screen actually sent it), and real delivery
+timestamps (**Timestamp** vs. **Delivered At**, so you can tell "sent" and
+"actually delivered" apart). KPIs: Total Communications, Sent, Delivered,
+Failed — genuine delivery tracking, not just a send log.
+
+## Related
+
+- [Notifications](./communications-notifications.md)

package/bundle/docs/applications/hcm/communications-notifications.md

@@ -0,0 +1,31 @@
+---
+title: Notifications
+audience: tenant
+---
+
+# Notifications (HCM)
+
+This page documents the shipped **Notifications** screen
+(`hcm-communications`) — your central inbox and the rule builder every
+other Communications screen sends through. Not for plugin developers.
+
+## Your inbox
+
+Every notification shows its Recipient, Title, Category, Priority,
+whether it's been Read, and Status (including **Failed**, if a
+notification genuinely couldn't be delivered — not silently dropped).
+KPIs: Total, Unread, Important, Failed.
+
+## The rule builder
+
+A no-code **Notification Rule** builder: event → condition → recipient →
+template → channel — set up "when X happens, notify Y using template Z
+over channel W" without writing any code.
+
+Announcements, Employee Communications, and the template screens all
+route through this same rule engine.
+
+## Related
+
+- [Announcements & Employee Communications](./communications-announcements.md)
+- [Email Templates, SMS Templates & Push Notifications](./communications-templates.md)

package/bundle/docs/applications/hcm/communications-templates.md

@@ -0,0 +1,35 @@
+---
+title: Email Templates, SMS Templates & Push Notifications
+audience: tenant
+---
+
+# Email Templates, SMS Templates & Push Notifications (HCM)
+
+This page documents three shipped **Communications** template screens
+(`hcm-communications`) — all sharing the same real lifecycle: Draft → In
+Review → Published → Archived, and a real **Version** number that
+increments as a template changes, so you're never silently editing a
+template that's already in use. Not for plugin developers.
+
+## Email Templates
+
+Each template has a Code, Name, Category, and Language, and tracks
+**Usage Count** — a real count of how many times it's actually been sent,
+so you can see which templates are genuinely in use vs. dead weight.
+
+## SMS Templates
+
+Same shape as Email Templates, plus what actually matters for SMS: a
+live **Characters** count, **Segments** (how many SMS message parts your
+text will be split into — costs and delivery reliability both depend on
+this), and **Encoding**, calculated as you type so you know before you
+publish, not after your first real send.
+
+## Push Notifications
+
+Templates for title/body/deep-link/actions, with the same lifecycle and
+versioning, plus a **Priority** and **Type** per template.
+
+## Related
+
+- [Notifications](./communications-notifications.md)

package/bundle/docs/applications/hcm/compensation-allowances-benefits.md

@@ -0,0 +1,44 @@
+---
+title: Allowances & Benefits
+audience: tenant
+---
+
+# Allowances & Benefits (HCM)
+
+This page documents two shipped **Compensation** screens
+(`hcm-compensation`) covering per-employee ongoing entitlements. Not for
+plugin developers.
+
+## Allowances
+
+**New Allowance** — pick the **Employee**, **Allowance Type**, and
+**Category**, then choose how it's calculated:
+
+- **Fixed Amount** — a flat amount per payment.
+- **Percentage** — a percentage of the employee's Base Salary (you
+  provide the base salary; the calculated amount is worked out for you).
+
+Set the **Frequency** (how often it's paid), an optional **Maximum
+Amount** cap, **Tax Treatment**, and **Effective From/To** dates. **Save &
+Submit** sends it for a two-stage approval rather than applying
+immediately — you'll see it move from Draft through Pending Approval to
+Active in the KPI row (Total Allowances, Draft, Pending Approval, Active).
+
+> **Note:** there's a separate Allowances screen inside the
+> [Benefits module](./benefits-allowances.md) too, for admin-configured
+> allowance *definitions* rather than per-employee amounts. If this isn't
+> the screen you're looking for, check there.
+
+## Benefits
+
+**New Benefit** — pick the **Employee**, **Benefit Type**, **Category**,
+**Plan** name, and **Provider**. Set the **Coverage Type** and **Coverage
+Amount**, the **Premium**, and how the cost is split — **Employer
+Contribution %** and **Employee Contribution %** — plus **Tax Treatment**
+and Effective From/To. The Total Cost shown in the grid reflects the real
+premium and contribution split you've set, not a placeholder. Same
+Save & Submit → two-stage approval flow as Allowances.
+
+## Related
+
+- [Bonus Plans & Incentive Plans](./compensation-bonus-incentive.md)

package/bundle/docs/applications/hcm/compensation-analytics.md

@@ -0,0 +1,30 @@
+---
+title: Compensation Dashboard & Reports
+audience: tenant
+---
+
+# Compensation Dashboard & Reports (HCM)
+
+This page documents two shipped **Compensation** analytics screens
+(`hcm-compensation`). Not for plugin developers.
+
+## Compensation Dashboard
+
+12 real KPI cards pulled together from every Compensation screen: Cycles
+(total and open), Total Cycle Budget, Total Approved Increases, Active
+Bonus Plans, Total Bonus Budget, Total Incentive Budget, Total Allowance
+Cost, Total Benefit Cost, Total/Active Equity Grants, and Estimated Equity
+Value. Use this for a real, at-a-glance read of your whole compensation
+spend.
+
+## Compensation Reports
+
+The same kind of real KPIs (Cycles, Salary Planning Entries, Salary
+Reviews, Merit Increases, Allowances, Benefits, Bonus Plans, Incentive
+Plans, Equity Grants, plus the budget/value totals) presented alongside a
+catalog of standard reports — click through from here into the specific
+screen behind each number.
+
+## Related
+
+- [Salary Planning, Salary Review & Merit Increase](./compensation-salary.md)

package/bundle/docs/applications/hcm/compensation-bonus-incentive.md

@@ -0,0 +1,35 @@
+---
+title: Bonus Plans & Incentive Plans
+audience: tenant
+---
+
+# Bonus Plans & Incentive Plans (HCM)
+
+This page documents two shipped **Compensation** configuration screens
+(`hcm-compensation`). Not for plugin developers.
+
+## Bonus Plans
+
+**New Bonus Plan** — set the Plan name/code, **Bonus Type**, **Plan
+Period**, and **Target Type**, plus a **Target %** for how big the bonus
+is relative to salary. Split how the bonus is weighted across **Company
+Weight %**, **Team Weight %**, and **Individual Weight %** (these should
+add up to 100% between them, since they define how much of the bonus
+depends on company vs. team vs. individual performance). Set a **Budget**,
+a **Minimum Payout** and **Maximum Payout** to cap it, and a **Payout
+Date**. **Save & Submit** puts it through review (Draft → Pending Review →
+Active, tracked in the KPI row).
+
+## Incentive Plans
+
+**New Incentive Plan** — similar shape to Bonus Plans, but built around up
+to three named performance metrics: **Metric 1/2/3 Name** and **Metric
+1/2/3 Weight %** (e.g. "Sales Revenue" at 60%, "Customer Satisfaction" at
+40%), a **Target Value**, and a **Calculation Frequency** for how often
+payout is worked out. Same Budget/Minimum/Maximum Payout and Payout Date
+fields as Bonus Plans, and the same Save & Submit review flow.
+
+## Related
+
+- [Allowances & Benefits](./compensation-allowances-benefits.md)
+- [Equity & Stock](./compensation-equity.md)

package/bundle/docs/applications/hcm/compensation-cycles.md

@@ -0,0 +1,49 @@
+---
+title: Compensation Cycles
+audience: tenant
+---
+
+# Compensation Cycles (HCM)
+
+This page documents the shipped **Compensation Cycles** screen
+(`hcm-compensation`) — the annual/periodic process every other
+Compensation screen (Salary Planning, Salary Review, Merit Increase,
+Allowances, Bonus Plans, Incentive Plans, Equity/Stock) runs inside of.
+Not for plugin developers.
+
+## Starting a new cycle
+
+Click **+ New Cycle** and fill in:
+
+- **Cycle Name** and **Cycle Code** — how you'll identify this cycle
+  elsewhere.
+- **Cycle Type** — Annual Merit, Bonus, Cost of Living, Equity Adjustment,
+  Incentive, Market Adjustment, Mid-Year, Off-Cycle, Promotion, Retention,
+  or Custom. Pick whichever matches what you're actually running — this
+  drives how the cycle is categorized and reported on later.
+- **Fiscal Year** and **Effective Date** — when the changes made under
+  this cycle should apply from.
+- **Budget Amount** and **Currency** — your overall budget for the cycle.
+- **Owner** — who's running it.
+
+A new cycle starts in **Configuring** status — set it up fully before you
+open it for real use.
+
+## Running a cycle
+
+Once you're ready, open the cycle and move it through its stages via
+**Activate**, and eventually **Close Cycle** once every compensation
+change under it is finalized. The KPI row at the top of the list screen
+always shows you Total Cycles and how many are Draft / Open / Closed, so
+you can see at a glance what still needs attention.
+
+## Checking a cycle's progress
+
+Open a cycle to see its detail: budget vs. planned vs. approved amount,
+how many employees are eligible, and its start/end dates — so you can
+track whether spend is tracking against budget before you close it out.
+
+## Related
+
+- [Salary Planning, Salary Review & Merit Increase](./compensation-salary.md)
+- [Compensation Dashboard & Reports](./compensation-analytics.md)