@sparkerp/plugin-sdk 0.1.0 → 1.0.0

package/bundle/docs/applications/hcm/admin-access-policies.md

@@ -0,0 +1,38 @@
+---
+title: Access Policies
+audience: tenant
+---
+
+# Access Policies (HCM Administration)
+
+This page documents the shipped **Access Policies** screen
+(`hcm-admin-console`) — real, tenant-wide security settings for HCM. Not
+for plugin developers.
+
+## What you can configure
+
+- **Session Policy** — Idle Timeout (minutes), Absolute Timeout (hours),
+  Concurrent Session Limit.
+- **Security Policy** — CAPTCHA After Failed Attempts, Allowed Login
+  Start/End Hour, and an Enforce Strict Sessions toggle.
+
+The page loads the real current values when you open it, and Save writes
+both policies back for real — these are genuine tenant-wide security
+controls, not a mock settings form.
+
+## Known gaps
+
+- **IP allow/deny lists and allowed-countries aren't editable here** —
+  those values exist and can be read via a direct API call, but this
+  screen has no editor for list-type fields yet (a real platform
+  limitation in how this page's action-chain engine handles lists, not an
+  oversight).
+- **No access-policy "wizard"** (subjects/resources/conditions/scoped
+  rules) — this screen covers real, existing tenant-wide security
+  settings, not a general-purpose access-control rule builder. Field/
+  record/menu/screen-level permission control lives in the separate,
+  tenant-wide Permission Designer instead, not on this screen.
+
+## Related
+
+- [HCM Roles & Permissions](./roles-permissions.md)

package/bundle/docs/applications/hcm/admin-approval-hierarchies.md

@@ -0,0 +1,33 @@
+---
+title: Approval Hierarchies
+audience: tenant
+---
+
+# Approval Hierarchies (HCM Administration)
+
+This page documents the shipped **Approval Hierarchies** screen
+(`hcm-admin-console`) — a real, read-only view of every approval workflow
+definition running across HCM. Not for plugin developers.
+
+## What you see
+
+A grid of every real workflow definition (name, description, status,
+version, last updated) — the same underlying engine that actually runs
+approvals for leave, transfers, promotions, resignations, expenses,
+timesheets, and everything else in HCM. This isn't a mock summary; it's
+the real definitions.
+
+## What isn't here
+
+- **You can't create, edit, publish, version, or clone a hierarchy from
+  this screen** — that stays in Studio's own Workflow Designer, the
+  correct place to author a real workflow.
+- **Dollar-limit approval tiers** (e.g. "a manager can approve expenses up
+  to $500") are a real, separate feature managed in Studio's own Approval
+  Permissions screen, not shown here.
+- No visual drag-and-drop canvas, no conflict detection, no import/export
+  JSON on this screen.
+
+## Related
+
+- [HCM Navigation & Approvals](./navigation-and-approvals.md)

package/bundle/docs/applications/hcm/admin-data-transfer.md

@@ -0,0 +1,40 @@
+---
+title: Data Export & Data Import
+audience: tenant
+---
+
+# Data Export & Data Import (HCM Administration)
+
+This page documents two shipped **Administration** screens
+(`hcm-admin-console`) for bulk moving data in and out of a small set of
+HCM reference tables. Not for plugin developers.
+
+## Data Export
+
+Pick an entity from the list (currently Leave Type Category, Leave Type,
+Organization Tag) and **Export** — downloads a real CSV of every row.
+
+## Data Import
+
+Pick the same entity, upload a CSV, and each row is created as a real
+record — one at a time, its own transaction and permission check, exactly
+like creating it by hand. If one row is bad (e.g. missing a required
+field), that row fails cleanly and every other valid row still gets
+created — one bad row never blocks the rest of your file.
+
+CSV headers must match the entity's real field names directly — there's
+no column-mapping step.
+
+## Known gaps
+
+- **Only 3 entities are supported** — not an arbitrary-entity picker.
+- **No XLSX or JSON**, CSV only.
+- **No dedup/merge on import** — every row is a create, not an
+  upsert.
+- **No mapping wizard** — your CSV's column headers need to already match
+  the real field names.
+- **No filtering on export** — it's the whole table or nothing.
+
+## Related
+
+- [HCM Permissions Catalog](./admin-permissions-catalog.md)

package/bundle/docs/applications/hcm/admin-hcm-users.md

@@ -0,0 +1,35 @@
+---
+title: HCM Users
+audience: tenant
+---
+
+# HCM Users (HCM Administration)
+
+This page documents the shipped **HCM Users** screen (`hcm-admin-console`)
+— a real, live view over the platform's own user accounts. Not for plugin
+developers.
+
+## What you see
+
+Search and filter by status, with a grid of Username, Email, Mobile,
+Status, and Created date — real accounts, not a mock list. Click a user
+to open a detail drawer with their full record and four real actions:
+**Activate**, **Deactivate**, **Lock**, **Unlock**.
+
+## What isn't here
+
+This screen deliberately doesn't duplicate everything a user account can
+do — it covers status management only:
+
+- **Creating a user, resetting a password, or issuing a temporary
+  password** — not here; these stay in Studio's own user management
+  screens.
+- **Assigning HCM roles** — go to [HCM Roles & Permissions](./roles-permissions.md)
+  instead; role assignment isn't duplicated on this screen.
+- **Bulk import/export of users, or editing role assignments by ID** —
+  Studio only.
+
+## Related
+
+- [HCM Roles & Permissions](./roles-permissions.md)
+- [HCM Permissions Catalog](./admin-permissions-catalog.md)

package/bundle/docs/applications/hcm/admin-logs.md

@@ -0,0 +1,57 @@
+---
+title: System Logs, Audit Logs & Activity Logs
+audience: tenant
+---
+
+# System Logs, Audit Logs & Activity Logs (HCM Administration)
+
+This page documents three shipped **Administration** screens
+(`hcm-admin-console`) — three different lenses over the exact same real
+audit event log, not three separate logging systems. Not for plugin
+developers.
+
+## The shared data
+
+All three screens read the platform's own Centralized Audit Framework —
+real, live events (6,900+ real rows in a typical tenant), not sample
+data. Every event has a Timestamp, an Actor/User, a Category, an
+Action/Activity, a Resource/Entity Type, a Record, a Module, a
+Result/Status, a Source, and a Correlation/Request ID. Click any row to
+open a detail drawer with the full field set plus IP Address and Region.
+
+## System Logs
+
+The original, general-purpose view — free-text search plus Category and
+Success filters.
+
+## Audit Logs
+
+The same data, relabeled for a security/compliance lens (Actor, Category,
+Action, Resource Type, Result), with a real date-range filter added on
+top (filter by when an event occurred, not just search by text).
+
+## Activity Logs
+
+The same data again, relabeled for a "who did what" timeline lens (User,
+Activity Type, Activity, Entity, Status) — same filters as Audit Logs,
+just renamed to read like a user activity feed rather than a compliance
+log.
+
+## Known gaps
+
+- **No before/after field diff** — the underlying table never records old
+  vs. new values for a create/update/delete event, so the detail drawer
+  shows a disclosure note here rather than fabricating a changes table.
+- **No login/authentication/security event category exists yet** — real
+  categories observed are only `crud`, `configuration`, `job`,
+  `communication`, `plugin`.
+- **IP Address and Correlation ID are always empty** in practice — shown
+  as columns/fields but nothing currently populates them.
+- **Result is a plain success/fail flag**, not a richer
+  success/failed/denied/partial/error breakdown.
+- **No tablet-specific compact layout** — tablet renders the same stacked
+  layout as mobile.
+
+## Related
+
+- [Data Export & Data Import](./admin-data-transfer.md)

package/bundle/docs/applications/hcm/admin-permissions-catalog.md

@@ -0,0 +1,64 @@
+---
+title: HCM Permissions Catalog
+audience: tenant
+---
+
+# HCM Permissions Catalog (HCM Administration)
+
+This page documents the shipped **HCM Permissions** screen
+(`hcm-admin-console`) — a real governance catalog of every permission in
+HCM, layered on top of (never replacing) the platform's own real
+authorization engine. Not for plugin developers.
+
+> **Not the same thing as [HCM Roles & Permissions](./roles-permissions.md).**
+> That screen is where you actually grant permissions to roles — this one
+> is a documentation/governance catalog of what permissions exist, what
+> they depend on, and which roles use them. Think of this as the
+> reference library; the Roles screen is where the real granting happens.
+
+## What you see
+
+Search and filter a real, live catalog of permission entries — Module,
+Resource, Action are all sortable/filterable grid columns.
+
+## A permission's detail view
+
+Four tabs:
+
+- **Overview** — the permission's own definition.
+- **Dependencies** — other permissions this one depends on; add or remove
+  a dependency directly here.
+- **Roles** — which roles actually use this permission.
+- **Audit History** — a real, live change log for this specific
+  permission entry.
+
+## Lifecycle
+
+A permission entry moves through **Activate**, **Deprecate**, and
+**Deactivate** — each a real status change you can confirm persisted by
+reopening the record.
+
+## Import/Export
+
+Bulk import and export reuse the same [Data Export & Data Import](./admin-data-transfer.md)
+screens — this entity is on their allow-list, not a separate mechanism.
+
+## Known gaps
+
+- **No interactive permission-tree visualization** — module/resource/
+  action are grid columns you can sort and filter by, not a visual tree.
+- **Dependency-cycle prevention only catches direct self-reference**, not
+  a longer chain (A depends on B depends on C depends on A) — the
+  underlying engine has no general graph-cycle check.
+- **No multi-row bulk activate/deactivate** — use the single-record
+  lifecycle buttons in the detail drawer instead.
+- **The grid doesn't always visually refresh right after a lifecycle
+  action** — the underlying change is always real and correct (confirmed
+  immediately in the detail drawer itself), but the grid row may need a
+  manual page reload to show it; a live-refresh convenience gap, not a
+  data-correctness one.
+
+## Related
+
+- [HCM Roles & Permissions](./roles-permissions.md)
+- [Data Export & Data Import](./admin-data-transfer.md)

package/bundle/docs/applications/hcm/ai-intelligence-overview.md

@@ -0,0 +1,37 @@
+---
+title: AI Dashboard, Employee Insights & Performance Insights
+audience: tenant
+---
+
+# AI Dashboard, Employee Insights & Performance Insights (HCM)
+
+This page documents three shipped **AI & Intelligence** screens
+(`hcm-ai-intelligence`). Not for plugin developers.
+
+> **What "AI" means on this module, honestly:** nothing here is a machine
+> learning model or a generative AI system. Every score, prediction, and
+> recommendation across this whole module is computed by the platform's
+> real, deterministic **Rule Engine** — chained business rules over your
+> real data (tenure, performance ratings, attendance, skills, and so on),
+> not a trained model. Think "explainable scoring system," not "AI that
+> learns." Every number traces back to a real, inspectable calculation.
+
+## AI Dashboard
+
+Cross-company workforce intelligence: headcount and attrition-rate KPIs
+from real data, a real attrition-risk distribution (see
+[Attrition Prediction](./ai-intelligence-people-risk.md)), and sentiment
+aggregates (see [Employee Sentiment](./ai-intelligence-people-risk.md)).
+
+## Employee Insights
+
+A per-employee intelligence layer — pick an employee and see their real
+performance, attendance, and leave data pulled together in one view.
+
+## Performance Insights
+
+Real average/group-by KPIs over your actual goals and appraisals data.
+
+## Related
+
+- [Attrition Prediction, Workforce Forecasting & Employee Sentiment](./ai-intelligence-people-risk.md)

package/bundle/docs/applications/hcm/ai-intelligence-people-risk.md

@@ -0,0 +1,33 @@
+---
+title: Attrition Prediction, Workforce Forecasting & Employee Sentiment
+audience: tenant
+---
+
+# Attrition Prediction, Workforce Forecasting & Employee Sentiment (HCM)
+
+This page documents three shipped **AI & Intelligence** screens
+(`hcm-ai-intelligence`). See
+[AI Dashboard](./ai-intelligence-overview.md#what-ai-means-on-this-module-honestly)
+for what "AI" actually means here — real rule-based scoring, not a
+trained model. Not for plugin developers.
+
+## Attrition Prediction
+
+Each employee gets a real risk score computed by 16 chained rules —
+banding tenure, performance, and absence, summing them, then banding the
+result into a risk level. It's a real, explainable calculation, not a
+black-box prediction — you can trace exactly why someone was flagged.
+
+## Workforce Forecasting
+
+A real rule pipeline computes a closing headcount and workforce gap for a
+period, from your actual current data.
+
+## Employee Sentiment
+
+Real sentiment responses, classified by the rule engine, with real
+aggregate KPIs.
+
+## Related
+
+- [AI Dashboard, Employee Insights & Performance Insights](./ai-intelligence-overview.md)

package/bundle/docs/applications/hcm/ai-intelligence-recruitment.md

@@ -0,0 +1,37 @@
+---
+title: Recruitment Intelligence, Candidate Matching & Resume Screening
+audience: tenant
+---
+
+# Recruitment Intelligence, Candidate Matching & Resume Screening (HCM)
+
+This page documents three shipped **AI & Intelligence** screens
+(`hcm-ai-intelligence`). See
+[AI Dashboard](./ai-intelligence-overview.md#what-ai-means-on-this-module-honestly)
+for what "AI" actually means here. Not for plugin developers.
+
+## Recruitment Intelligence
+
+Real aggregate counts and breakdowns over your actual requisitions,
+applications, and interviews.
+
+## Candidate Matching
+
+A 13-rule chained pipeline scores each candidate against a role: skills
+match percentage, an experience-fit banding, and an overall explainable
+score — real structured-field matching, not free-text resume parsing.
+
+## Resume Screening
+
+**Important:** this screen does not actually read or parse resume files
+— there's no OCR/NLP text-extraction pipeline anywhere in this platform.
+It reuses the same structured candidate-profile matching as Candidate
+Matching above (mandatory-requirement coverage, experience fit, overall
+score), presented as a "screening" result. If you're expecting a system
+that reads an uploaded resume PDF and extracts skills from it
+automatically, that doesn't exist — every number here comes from
+structured fields already on the candidate's profile.
+
+## Related
+
+- [AI Dashboard, Employee Insights & Performance Insights](./ai-intelligence-overview.md)

package/bundle/docs/applications/hcm/ai-intelligence-tools.md

@@ -0,0 +1,39 @@
+---
+title: Skills Intelligence, Compensation Intelligence, AI Assistant & Recommendations
+audience: tenant
+---
+
+# Skills Intelligence, Compensation Intelligence, AI Assistant & Recommendations (HCM)
+
+This page documents four shipped **AI & Intelligence** screens
+(`hcm-ai-intelligence`). See
+[AI Dashboard](./ai-intelligence-overview.md#what-ai-means-on-this-module-honestly)
+for what "AI" actually means here. Not for plugin developers.
+
+## Skills Intelligence
+
+Real skill-gap analytics — gap and gap-status computed server-side from
+your actual employee skill records.
+
+## Compensation Intelligence
+
+Real compensation analytics computed from your actual salary planning
+data.
+
+## AI Assistant
+
+**Important:** this is not a free-text chat with an AI model. It's a
+structured Q&A interface — a curated set of common HR questions, each
+mapped to a real data lookup. Pick a question; get a real answer from
+your real data. You can't ask it something outside that curated list.
+
+## AI Recommendations
+
+Real rows, each synthesized from real KPI observations across this
+module's own other screens (attrition risk level, sentiment, and more) —
+not AI-generated text. Every recommendation traces back to a real
+underlying number.
+
+## Related
+
+- [AI Dashboard, Employee Insights & Performance Insights](./ai-intelligence-overview.md)

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

@@ -0,0 +1,31 @@
+---
+title: Attendance, Leave, Payroll & Compensation Analytics
+audience: tenant
+---
+
+# Attendance, Leave, Payroll & Compensation Analytics (HCM)
+
+This page documents four shipped **Analytics & Reports** screens
+(`hcm-analytics-reports`) — real, read-only analytics, not sample data.
+Not for plugin developers.
+
+## Attendance
+
+Real attendance analytics across your company.
+
+## Leave
+
+Real leave analytics.
+
+## Payroll
+
+Real payroll analytics.
+
+## Compensation
+
+Real compensation analytics.
+
+## Related
+
+- [HCM Analytics, Headcount, Attrition & Workforce Analytics](./analytics-overview.md)
+- [Workforce Cost & Report Builder](./analytics-tools.md)

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

@@ -0,0 +1,31 @@
+---
+title: HCM Analytics, Headcount, Attrition & Workforce Analytics
+audience: tenant
+---
+
+# HCM Analytics, Headcount, Attrition & Workforce Analytics (HCM)
+
+This page documents four shipped **Analytics & Reports** screens
+(`hcm-analytics-reports`) — real, read-only analytics dashboards. Every
+KPI, chart, and list on every screen in this module is wired to a real
+Data Service, not sample data. Not for plugin developers.
+
+## HCM Analytics
+
+The organization-wide analytics landing page.
+
+## Headcount
+
+Headcount trends and breakdowns.
+
+## Attrition
+
+Real attrition metrics and trends.
+
+## Workforce Analytics
+
+A broader workforce composition view.
+
+## Related
+
+- [Attendance, Leave, Payroll & Compensation Analytics](./analytics-operations.md)

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

@@ -0,0 +1,36 @@
+---
+title: Performance, Recruitment, Training, Productivity & Diversity Analytics
+audience: tenant
+---
+
+# Performance, Recruitment, Training, Productivity & Diversity Analytics (HCM)
+
+This page documents five shipped **Analytics & Reports** screens
+(`hcm-analytics-reports`). Not for plugin developers.
+
+## Performance
+
+Real performance analytics.
+
+## Recruitment
+
+Real recruitment analytics.
+
+## Training
+
+Real training/learning analytics.
+
+## Employee Productivity
+
+A real proxy metric built from existing data — Time Utilization is
+derived from your real attendance status mix, not a separately-tracked
+productivity score.
+
+## Diversity & Inclusion
+
+A real, aggregated breakdown — built by reusing existing headcount data,
+not a separate D&I data set.
+
+## Related
+
+- [HCM Analytics, Headcount, Attrition & Workforce Analytics](./analytics-overview.md)

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

@@ -0,0 +1,35 @@
+---
+title: Workforce Cost & Report Builder
+audience: tenant
+---
+
+# Workforce Cost & Report Builder (HCM)
+
+This page documents two shipped **Analytics & Reports** screens
+(`hcm-analytics-reports`). Not for plugin developers.
+
+## Workforce Cost
+
+Real cost analytics, built on top of your real Payroll data.
+
+## Report Builder
+
+A genuine, working ad-hoc report builder — not a mock-up. Pick a data
+source, a group-by field, a value field, and an aggregation (sum, count,
+etc.), optionally pivot on another column, and optionally filter by one
+condition (field, operator, value — equals, not-equals, greater/less
+than, in-list, contains). Preview live, then **Run Selected Report**, and
+**Save/Publish** it for reuse. Export the result as CSV.
+
+## Known gaps
+
+- **Only one filter condition at a time** — not a fully dynamic
+  add/remove list of conditions.
+- **No scheduling or emailing** of reports.
+- **No drag-and-drop layout or chart visualizations** — results render as
+  a table.
+- **No sharing/permissions UI or report templates** yet.
+
+## Related
+
+- [HCM Analytics, Headcount, Attrition & Workforce Analytics](./analytics-overview.md)

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

@@ -0,0 +1,30 @@
+---
+title: Asset Audits
+audience: tenant
+---
+
+# Asset Audits (HCM)
+
+This page documents the shipped **Asset Audits** screen (`hcm-assets`) —
+audit campaigns that verify your recorded assets match physical reality.
+Not for plugin developers.
+
+## Running an audit
+
+**New Audit** — name it, give it an Audit Number, Audit Type, an assigned
+Auditor, a Start/End Date, and a Scope description of what's actually
+being counted (e.g. "all laptops in the Mumbai office"). Only assets in
+categories with **Audit Required** turned on (set in
+[Asset Categories](./assets-inventory.md)) are pulled into an audit.
+
+## Reviewing results
+
+The grid shows how many Assets were in scope and how many Exceptions were
+found (missing, extra, or mismatched condition) for each audit, alongside
+its Status. KPIs: Total Audits, In Progress, Completed. This never
+silently rewrites your Inventory, Allocation, or Maintenance records for
+you — you review and resolve exceptions yourself.
+
+## Related
+
+- [Asset Inventory & Asset Categories](./assets-inventory.md)

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

@@ -0,0 +1,36 @@
+---
+title: Asset Allocation & Returns
+audience: tenant
+---
+
+# Asset Allocation & Returns (HCM)
+
+This page documents two shipped **Assets** screens (`hcm-assets`) covering
+who has custody of an asset. Not for plugin developers.
+
+## Asset Allocation
+
+**New Asset Allocation** — pick the Asset and the Employee, an
+**Allocation Type** (Permanent, Temporary, Project, or Loan — a Loan or
+Temporary allocation naturally implies you'll set an Expected Return
+Date), the Condition at time of allocation, Department, Location, a
+Reason, and Notes. New allocations go through **Submit for Approval**,
+then once approved, **Mark In Use** and **Acknowledge** (the recipient
+confirming they've received it) — tracked via the KPI row (Pending
+Approval, Awaiting Acknowledgement, In Use).
+
+## Asset Returns
+
+**New Asset Return** — pick the Asset, Employee, and (if applicable) the
+specific Allocation being returned, a Return Type, Return Reason,
+Requested/Scheduled Date, and Notes. The grid tracks the return's
+**Outcome** separately from its Status, and reports damage explicitly —
+the KPI row (Pending Returns, Damage Reported, Completed) makes it easy
+to spot how often returned equipment comes back damaged. This creates its
+own return record rather than editing the original allocation, so the
+full history stays intact.
+
+## Related
+
+- [Asset Inventory & Asset Categories](./assets-inventory.md)
+- [Asset Maintenance](./assets-maintenance.md)

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

@@ -0,0 +1,34 @@
+---
+title: Asset Inventory & Asset Categories
+audience: tenant
+---
+
+# Asset Inventory & Asset Categories (HCM)
+
+This page documents two shipped **Assets** screens (`hcm-assets`). Not for
+plugin developers.
+
+## Asset Inventory
+
+**New Asset** — Asset Name, Asset Number, Asset Type, Category,
+Manufacturer, Model, Serial Number, Purchase Date, Warranty Expiry, and
+Condition. The grid shows Category, Location, Condition, Status, and who
+it's Assigned To. KPIs: Total Assets, Available, Assigned, Under Repair —
+so you can see at a glance how much of your inventory is actually sitting
+idle vs. deployed.
+
+## Asset Categories
+
+**New Asset Category** — Category Name/Code, an optional Parent Category
+(to build a category hierarchy), Display Order, and three toggles that
+control what a category actually enables downstream: **Allow Employee
+Assignment** (can assets in this category be allocated to a person at
+all), **Maintenance Enabled** (does this category get maintenance
+tracking), and **Audit Required** (does this category get pulled into
+audit campaigns). Set these deliberately — they change what other Assets
+screens let you do with assets in this category, not just cosmetic
+grouping.
+
+## Related
+
+- [Asset Allocation & Returns](./assets-custody.md)