@sparkerp/plugin-sdk 0.1.0 → 1.0.0

package/bundle/docs/applications/hcm/recruitment-candidates.md

@@ -0,0 +1,33 @@
+---
+title: Candidates, Candidate Pools & Resumes
+audience: tenant
+---
+
+# Candidates, Candidate Pools & Resumes (HCM)
+
+This page documents three shipped **Recruitment** screens
+(`hcm-recruitment`) covering the people side of hiring — independent of
+any specific opening they're applying to. Not for plugin developers.
+
+## Candidates
+
+The candidate master — a person's profile, kept separate from any one
+opening they apply to. A candidate can have applied to multiple openings
+over time; this is their one, ongoing record.
+
+## Candidate Pools
+
+A bench of candidates you're tracking for future openings, even though
+they're not actively applying to anything right now — useful for keeping
+in touch with strong candidates from past searches.
+
+## Resumes
+
+Real file storage for candidate resumes/CVs, with version history (upload
+a new version rather than losing the old one), tagging, and activity
+tracking.
+
+## Related
+
+- [Job Requisitions, Job Openings & Careers](./recruitment-requisitions-and-openings.md)
+- [Applications, Screening, Interviews & Assessments](./recruitment-pipeline.md)

package/bundle/docs/applications/hcm/recruitment-offers.md

@@ -0,0 +1,32 @@
+---
+title: Offers, Offer Approvals & Background Verification
+audience: tenant
+---
+
+# Offers, Offer Approvals & Background Verification (HCM)
+
+This page documents three shipped **Recruitment** screens
+(`hcm-recruitment`) covering the final stretch of hiring — making an
+offer, getting it approved, and checking the candidate out before they
+start. Not for plugin developers.
+
+## Offers
+
+Create and track job offers, each going through a real approval chain:
+Hiring Manager → HR → Finance, conditionally, depending on the offer.
+
+## Offer Approvals
+
+A worklist of offers waiting for your approval — the same underlying
+approval queue every other approval in the platform uses, just scoped to
+offers.
+
+## Background Verification
+
+Once a candidate accepts an offer and their Application reaches HIRED
+status, run their background check — education, employment history,
+criminal record, references, and address, each tracked as its own item.
+
+## Related
+
+- [Applications, Screening, Interviews & Assessments](./recruitment-pipeline.md)

package/bundle/docs/applications/hcm/recruitment-pipeline.md

@@ -0,0 +1,46 @@
+---
+title: Applications, Screening, Interviews & Assessments
+audience: tenant
+---
+
+# Applications, Screening, Interviews & Assessments (HCM)
+
+This page documents five shipped **Recruitment** screens
+(`hcm-recruitment`) that together form the hiring pipeline a candidate
+moves through for one specific opening: Candidate → **Application** →
+**Screening** → **Interview** → **Assessment**. Not for plugin developers.
+
+## Applications
+
+A candidate's participation in one specific opening — its own stage,
+status, source, assigned recruiter, screening result, and outcome. This is
+different from the Candidate record itself (the person) — one candidate
+can have several Applications over time, one per opening.
+
+## Screening
+
+The pre-interview evaluation stage. There's no AI-based resume screening
+here — this is a real but manual/structured evaluation step, not an
+automated matching engine.
+
+## Interviews
+
+A scheduled evaluation event tied to one Application.
+
+## Interview Panels
+
+Reusable, named groups of interviewers (each with a role like lead,
+technical, or HR) — set up a panel once and assign the whole group to an
+interview, instead of picking individual interviewers every time.
+
+## Assessments
+
+A real record of assessment results — but this doesn't include an actual
+online-testing platform, question bank, auto-grading, or a third-party
+assessment integration. You record the result; you don't administer the
+test from here.
+
+## Related
+
+- [Candidates, Candidate Pools & Resumes](./recruitment-candidates.md)
+- [Offers, Offer Approvals & Background Verification](./recruitment-offers.md)

package/bundle/docs/applications/hcm/recruitment-requisitions-and-openings.md

@@ -0,0 +1,33 @@
+---
+title: Job Requisitions, Job Openings & Careers
+audience: tenant
+---
+
+# Job Requisitions, Job Openings & Careers (HCM)
+
+This page documents three shipped **Recruitment** screens (`hcm-recruitment`)
+covering where a hire starts — getting approval to hire, then publishing
+the vacancy. Not for plugin developers.
+
+## Job Requisitions
+
+The starting point: request approval to hire for a role, including
+required skills. Goes through a real approval workflow, with a
+budget-threshold check along the way — a requisition above a certain
+budget needs an extra approval step.
+
+## Job Openings
+
+Once a requisition is approved, turn it into a publishable vacancy —
+what candidates actually see and apply to.
+
+## Careers
+
+Admin-side configuration for your careers page — branding and which
+openings are published where. This configures the admin side of career
+site presentation over your real Job Openings; it's not itself a public
+website candidates browse directly.
+
+## Related
+
+- [Candidates, Candidate Pools & Resumes](./recruitment-candidates.md)

package/bundle/docs/applications/hcm/roles-permissions.md

@@ -0,0 +1,129 @@
+---
+title: HCM Roles & Permissions
+audience: tenant
+---
+
+# HCM Roles & Permissions (HCM)
+
+This page documents the shipped **HCM Roles & Permissions** screen
+(`hcm-foundation`), for HR administrators managing who can do what inside the
+HCM application — not for plugin developers. If you're building a page like
+this one for your own plugin, see
+[Add your own app-owned roles & permissions](../../guides/add-app-owned-roles-and-permissions.md)
+instead.
+
+**Who this page is for:** whoever holds the **HCM Administrator** role.
+Anyone can open this page and browse the list of roles, but making any
+change — creating, editing, turning a role on/off, archiving, cloning,
+assigning it to someone, granting/removing a permission, bulk actions,
+exporting — needs the HCM Administrator role. If you try one of these
+without it, you'll see a clear "administrator role required" message.
+
+This page manages roles that only apply *inside HCM* — it's separate from
+the company-wide Roles Studio designer, which manages a different, broader
+set of roles.
+
+## Getting there
+
+`/app/hcm/administration/hcm-foundation/hcm-roles-permissions` (under HCM's
+Administration menu).
+
+## The list
+
+A grid of every role defined in this tenant's own HCM installation, with:
+
+- **Role** name and code
+- **Type** — `SYSTEM`, `STANDARD`, `CUSTOM`, `APPLICATION`, `POSITION`, or
+  `APPROVAL`
+- **Status** — `DRAFT`, `ACTIVE`, `INACTIVE`, or `ARCHIVED` (color-coded chip)
+- **Permissions** count and **Users** count
+- **System** flag — a small set of built-in roles (like the HCM
+  Administrator role itself) are marked system roles and can't be archived
+
+Use the column filters to narrow by type or status. Select multiple rows to
+**Activate** or **Deactivate** them in bulk — you'll get a confirmation
+dialog naming the action and how many roles it affects before anything
+happens.
+
+**Export** downloads the current role list as a CSV (admin-only, same as
+every mutation). There's no matching **import** yet — the platform's own
+file-upload block can't hand a page raw file bytes to send onward yet, so
+this is a one-way capability for now.
+
+## Creating a role
+
+**New Role** opens a dialog: Name and Description (required), Role Type,
+and an optional **Parent Role ID** — set this to make the new role inherit
+another role's permissions on top of its own (see
+[Role hierarchy](#role-hierarchy) below). There's also an **Administrator
+role** toggle; turning it on makes the new role itself `is_admin` — grant
+this carefully, since anyone assigned it gets full control of this page.
+
+## The role detail view
+
+Click any row to open its detail panel, with four tabs:
+
+### Overview
+
+The role's own fields (name, code, description, type, status), whether it's
+a system role, whether it's an administrator role, and how many users
+currently hold it. From here:
+
+- **Activate** / **Deactivate** — flips the role's status. A deactivated
+  role stops granting access immediately — anyone holding only that role
+  loses whatever it granted the moment it's deactivated, not on their next
+  login.
+- **Archive** — the closest thing to deleting a role. Not offered for
+  system roles.
+- **Clone** — makes a copy of the role (all its permissions, none of its
+  assigned users) under a new name you choose, for when you want a
+  near-identical role without rebuilding it from scratch.
+
+### Permissions
+
+The role's **effective** permissions — its own grants plus anything
+inherited from a parent role (see [Role hierarchy](#role-hierarchy)), each
+one showing whether it was inherited and from where.
+
+### Users
+
+Everyone currently assigned this role.
+
+### Audit History
+
+A real log of every change made to this role — created, activated,
+deactivated, archived, cloned, permission granted/revoked, and who did it
+and when — pulled from the platform's own audit trail.
+
+## Role hierarchy — one role can build on another
+
+Setting a **Parent Role** when you create a role means the new role
+automatically gets everything the parent role can do, on top of its own
+permissions. You can chain this up to 10 levels deep (a role's parent can
+have its own parent, and so on).
+
+This isn't just a label in the UI — it's checked for real every time
+someone tries to do something. So if you turn off a parent role, or remove
+one of its permissions, everything that inherits from it loses that access
+right away.
+
+## Known gaps
+
+- **No CSV import** — export only; see above.
+- **Reparenting an existing role** (changing its parent after creation) has
+  a real backend endpoint but isn't wired to any button on this page yet.
+- **Audit search is a substring match**, not an exact role-id match — so a
+  search for role id `5` can also surface unrelated entries mentioning
+  `15` or `50` in passing. A known, accepted precision trade-off, not a bug.
+- **The very first HCM Administrator can't be created from this page** —
+  every action on this page needs an administrator to already exist, so
+  there'd be no way to create the first one here. Instead, whoever already
+  holds your company's own "Tenant Owner"/"Tenant Admin" role is
+  automatically given the HCM Administrator role the first time HCM is set
+  up. If nobody on your tenant has HCM Administrator and you're stuck,
+  that's the thing to check.
+
+## Related
+
+- [Add your own app-owned roles & permissions](../../guides/add-app-owned-roles-and-permissions.md)
+  — the developer-facing guide, if you're building a similar page.

package/bundle/docs/applications/hcm/separation-clearance.md

@@ -0,0 +1,33 @@
+---
+title: Clearance, Asset Return & Offboarding Checklist
+audience: tenant
+---
+
+# Clearance, Asset Return & Offboarding Checklist — hcm-separation (HCM)
+
+This page documents three shipped screens in the **`hcm-separation`**
+module, covering the departing-employee checklist process. Not for plugin
+developers.
+
+## Clearance
+
+**New Clearance Case** — links directly to the real Resignation record,
+with a Target Completion Date. A clearance case is made up of individual
+tasks; click a task to mark it clear. KPIs: Total, Active, Completed,
+Exception (a task that couldn't be cleared normally).
+
+## Asset Return
+
+**New Asset Return Case** — links to both the Resignation and its
+Clearance Case (not a standalone record), with individual line items per
+asset and a Due Date. KPIs: Total, Active, Recovery (still chasing
+equipment back), Cleared.
+
+## Offboarding Checklist
+
+A checklist of offboarding tasks with one-click completion per task.
+
+## Related
+
+- [Resignation & Resignation Approval (Separation module)](./separation-resignation.md)
+- [Exit Interviews, Experience Letter & Relieving Letter](./separation-documents.md)

package/bundle/docs/applications/hcm/separation-documents.md

@@ -0,0 +1,28 @@
+---
+title: Exit Interviews, Experience Letter & Relieving Letter
+audience: tenant
+---
+
+# Exit Interviews, Experience Letter & Relieving Letter — hcm-separation (HCM)
+
+This page documents three shipped screens in the **`hcm-separation`**
+module. Not for plugin developers.
+
+## Exit Interviews
+
+Manage employee exit interviews and record their feedback.
+
+## Experience Letter
+
+Generate and issue employee experience letters.
+
+## Relieving Letter
+
+Generate and issue employee relieving letters — gated so it can only be
+issued once the appropriate conditions are met, not on demand at any
+point in the process.
+
+## Related
+
+- [Clearance, Asset Return & Offboarding Checklist](./separation-clearance.md)
+- [Final Settlement](./separation-final-settlement.md)

package/bundle/docs/applications/hcm/separation-final-settlement.md

@@ -0,0 +1,24 @@
+---
+title: Final Settlement
+audience: tenant
+---
+
+# Final Settlement — hcm-separation (HCM)
+
+This page documents the shipped **Final Settlement** screen in the
+**`hcm-separation`** module — the departing employee's final pay
+settlement. Not for plugin developers.
+
+## Creating a settlement
+
+**New Final Settlement** links directly to the real Resignation and
+Clearance Case records (not a standalone form) — Employee, Last Working
+Date, and a real Settlement Number. KPIs: Total, Pending, Pending
+Approval, Payment Pending, Completed — so you can tell "still being
+calculated," "waiting on sign-off," and "approved but not yet paid" apart,
+not just one generic "pending" bucket.
+
+## Related
+
+- [Clearance, Asset Return & Offboarding Checklist](./separation-clearance.md)
+- [Exit Reports](./separation-reports.md)

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

@@ -0,0 +1,23 @@
+---
+title: Exit Reports
+audience: tenant
+---
+
+# Exit Reports — hcm-separation (HCM)
+
+This page documents the shipped **Exit Reports** screen in the
+**`hcm-separation`** module — consolidated exit and attrition analytics.
+Not for plugin developers.
+
+## What you see
+
+KPIs: Total Exits, Separated, Exit Interviews Completed, Clearance
+Completed, Settlements Completed — a real, per-stage completion view
+across every exit currently in flight, not just a single "done" flag.
+Plus two charts: **Exit Reasons** (a breakdown of why people are leaving)
+and **Exit Process Status** (where exits currently stand across
+Resignation → Clearance → Settlement).
+
+## Related
+
+- [Resignation & Resignation Approval (Separation module)](./separation-resignation.md)

package/bundle/docs/applications/hcm/separation-resignation.md

@@ -0,0 +1,43 @@
+---
+title: Resignation & Resignation Approval (Separation module)
+audience: tenant
+---
+
+# Resignation & Resignation Approval — hcm-separation (HCM)
+
+This page documents two shipped screens in the **`hcm-separation`**
+module. Not for plugin developers.
+
+> **Important — this is a separate module from the Resignation screen
+> you may already know.** HCM ships **two independent** resignation
+> implementations, on two different underlying tables: this one
+> (`hcm-separation`, real `hcm_resignation` entity) and the one inside the
+> Employee module ([Resignation, Retirement, Termination & Exit](./offboarding-and-exit.md),
+> real `employee_resignation` entity). They are not the same data and
+> don't sync with each other. If a resignation you're looking for isn't
+> here, check the other one — and if your company uses both menus, be
+> deliberate about which one you actually use for real resignations, since
+> using both would split your data across two unrelated records.
+
+## Resignation
+
+**Submit Resignation** — Employee, Resignation Date, Reason, Reason
+Details, Proposed Last Working Day, and Notice Period Days. Each gets a
+real Resignation Number. Status moves through Submitted → Under Review →
+Approved → Notice → Clearance → Separated (or Withdrawn, if the employee
+changes their mind before it's finalized). KPIs: Total, Submitted, Under
+Review, Approved, Notice, Clearance, Separated, Withdrawn.
+
+## Resignation Approval
+
+A dedicated approval workbench showing exactly where each resignation
+sits in a real **three-stage chain**: Pending Manager → Pending HR →
+Pending Final — each stage tracked separately in the KPI row, so you can
+see whether a resignation is stuck with the manager, with HR, or waiting
+on final sign-off, rather than just a single generic "pending" bucket.
+KPIs: Pending Manager, Pending HR, Pending Final, Approved, Rejected.
+
+## Related
+
+- [Resignation, Retirement, Termination & Exit](./offboarding-and-exit.md) (the other module)
+- [Clearance, Asset Return & Offboarding Checklist](./separation-clearance.md)

package/bundle/docs/applications/hcm/settings-extensibility.md

@@ -0,0 +1,31 @@
+---
+title: Document Settings, Custom Fields, Custom Forms & Numbering Sequences
+audience: tenant
+---
+
+# Document Settings, Custom Fields, Custom Forms & Numbering Sequences (HCM)
+
+This page documents four shipped **Settings** screens
+(`hcm-settings-extended`) — how you extend HCM without code. Not for
+plugin developers.
+
+## Document Settings
+
+Tenant-wide document management policy.
+
+## Custom Fields
+
+Extend HCM entities with your own fields, without writing code.
+
+## Custom Forms
+
+Create and manage your own custom form definitions.
+
+## Numbering Sequences
+
+Configure automatic ID-generation sequences (e.g. how employee IDs or
+request numbers are formatted and incremented).
+
+## Related
+
+- [General, Organization & Employee Settings](./settings-general.md)

package/bundle/docs/applications/hcm/settings-general.md

@@ -0,0 +1,29 @@
+---
+title: General, Organization & Employee Settings
+audience: tenant
+---
+
+# General, Organization & Employee Settings (HCM)
+
+This page documents three shipped **Settings** screens
+(`hcm-settings-extended`) — tenant-wide defaults, separate from
+[HR Settings](./hr-settings.md)'s own category cards. Not for plugin
+developers.
+
+## General HCM Settings
+
+Tenant-wide default settings — one record per tenant.
+
+## Organization Settings
+
+Your organization profile and defaults, plus a register of Legal
+Entities.
+
+## Employee Settings
+
+Tenant-wide employee master/lifecycle defaults.
+
+## Related
+
+- [HR Settings](./hr-settings.md)
+- [Attendance, Leave, Payroll, Performance, Recruitment & Training Settings](./settings-module-defaults.md)

package/bundle/docs/applications/hcm/settings-integrations.md

@@ -0,0 +1,14 @@
+---
+title: Integrations
+audience: tenant
+---
+
+# Integrations (HCM)
+
+This page documents the shipped **Integrations** screen
+(`hcm-settings-extended`) — register and manage your tenant's integration
+connections. Not for plugin developers.
+
+## Related
+
+- [General, Organization & Employee Settings](./settings-general.md)

package/bundle/docs/applications/hcm/settings-module-defaults.md

@@ -0,0 +1,41 @@
+---
+title: Attendance, Leave, Payroll, Performance, Recruitment & Training Settings
+audience: tenant
+---
+
+# Attendance, Leave, Payroll, Performance, Recruitment & Training Settings (HCM)
+
+This page documents six shipped **Settings** screens
+(`hcm-settings-extended`) — tenant-wide policy defaults for each domain
+module. Not for plugin developers.
+
+## Attendance Settings
+
+Tenant-wide attendance integration and default policy.
+
+## Leave Settings
+
+Tenant-wide leave policy defaults, consumed by the [Leave](./leave-setup.md)
+module's own engine.
+
+## Payroll Settings
+
+Configuration-only policy defaults for [Payroll](./payroll-setup.md) — no
+salary calculation logic lives here, just defaults the payroll engine
+reads.
+
+## Performance Settings
+
+Tenant-wide policy defaults for [Performance](./performance-cycles-and-goals.md).
+
+## Recruitment Settings
+
+Tenant-wide numbering and process defaults for [Recruitment](./recruitment-requisitions-and-openings.md).
+
+## Training Settings
+
+Tenant-wide policy defaults for [Learning](./learning-catalog.md).
+
+## Related
+
+- [General, Organization & Employee Settings](./settings-general.md)

package/bundle/docs/applications/hcm/settings-process.md

@@ -0,0 +1,28 @@
+---
+title: Approval, Workflow & Notification Settings
+audience: tenant
+---
+
+# Approval, Workflow & Notification Settings (HCM)
+
+This page documents three shipped **Settings** screens
+(`hcm-settings-extended`) — tenant-wide process behavior. Not for plugin
+developers.
+
+## Approval Settings
+
+Tenant-wide approval SLA, escalation, and delegation defaults.
+
+## Workflow Settings
+
+Tenant-wide workflow engine defaults, consumed by HCM's own approval
+chains.
+
+## Notification Settings
+
+Tenant-wide notification channel and rate-limit policy.
+
+## Related
+
+- [HCM Navigation & Approvals](./navigation-and-approvals.md)
+- [Notifications](./communications-notifications.md)

package/bundle/docs/applications/hcm/shift-scheduling.md

@@ -0,0 +1,33 @@
+---
+title: Shifts, Scheduling & Rosters
+audience: tenant
+---
+
+# Shifts, Scheduling & Rosters (HCM)
+
+This page documents three shipped **Shift Scheduling** screens
+(`hcm-shift-scheduling`). Not for plugin developers.
+
+Each screen has a distinct, deliberate role:
+
+## Shifts
+
+Reusable work-shift templates — define the actual working hours a shift
+represents (e.g. "Morning 9-5"). This is the raw material everything else
+in this module is built from.
+
+## Scheduling
+
+The planner's working workspace — draft and adjust who's assigned to
+which shift, before anything is finalized.
+
+## Rosters
+
+The official, published, controlled version of a schedule — once
+Scheduling's draft is finalized, it becomes a Roster: what's actually
+communicated to employees and used operationally, as distinct from the
+planner's working draft.
+
+## Related
+
+- [Attendance — Dashboard, Daily Attendance, Register, Biometric & Devices](./attendance-core.md)

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

@@ -0,0 +1,26 @@
+---
+title: Talent Dashboard & Reports
+audience: tenant
+---
+
+# Talent Dashboard & Reports (HCM)
+
+This page documents two shipped **Talent** analytics screens
+(`hcm-talent`). Not for plugin developers.
+
+## Talent Dashboard
+
+Real KPI cards across talent profiles and high-potential counts, a real
+donut chart of talent category distribution (default / high-performer /
+high-potential / both), and a "Top Talent" grid pulling directly from
+your real Talent Profiles.
+
+## Talent Reports
+
+See [Succession Planning, Successor Candidates & Talent Reviews](./talent-succession.md#known-gaps)
+for what this screen actually is (a catalog of links into real data, not
+a report builder).
+
+## Related
+
+- [Talent Profiles, High Potential Employees & Talent Pools](./talent-profiles.md)

package/bundle/docs/applications/hcm/talent-career.md

@@ -0,0 +1,31 @@
+---
+title: Career Development & Career Paths
+audience: tenant
+---
+
+# Career Development & Career Paths (HCM)
+
+This page documents two shipped **Talent** screens (`hcm-talent`). Not for
+plugin developers.
+
+## Career Development
+
+An employee's career development plan — linked via real employee/manager/
+career-owner lookups, and (if it references a defined Career Path below)
+a real link to that path too. Goes through a real activation approval.
+
+## Career Paths
+
+Define career paths as a master template, made up of ordered steps shown
+inside the path's own detail view. Each path has a **Track** you choose
+from a configured list. New paths go through a real activation approval.
+
+## Known gaps
+
+- **Current/target role fields are free text**, not looked up from your
+  real job/position catalog — if you need to change a job title later,
+  it won't update automatically anywhere it's referenced.
+
+## Related
+
+- [Talent Profiles, High Potential Employees & Talent Pools](./talent-profiles.md)