CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository layout

All documentation content lives at the repository root. Key files:

docs.json                     # Site configuration: nav, branding, colours, fonts
index.mdx                     # Homepage
admin/                        # All admin-facing guides
  admin-hub.mdx
  ai/                         # AI settings, skill mapping, Empuls Copilot
  benefits/                   # Health & wellness, flexible benefits
  finance/                    # Subscription, budgets, wallets, points
  gifts/                      # Gifts, milestones, automate, onboarding, product-based, revoke, schedule
  integrations/               # HRMS, Slack, MS Teams, Google Workspace, webhooks, etc.
  platform-settings/          # Branding, org structure, notifications, feed settings
  programs/                   # Awards, leaderboard, promo points, campaigns, governance, etc.
  reports/                    # Platform reports and analytics
  security/                   # Info security, privacy, responsible AI, security settings
  surveys/                    # Survey types, eNPS, pulse, lifecycle, mood-o-meter, action plan
  user-authentication/        # SSO (Azure, SAML, Okta, Google), passwords, sessions, OAuth
  user-management/            # Manage employees, access control, delegation, login-as, exit
employees/                    # All employee-facing guides
  benefits/                   # Perks, fitness challenges, flexible benefits
  engagement/                 # Gamezone, quick links, yearbook
  getting-started/            # Log in, OTP/magic link, profile, mobile app, notifications, privacy
  recognitions/               # Appreciate colleagues, nominations, wall of fame, approvals, jury
  redemption/                 # Redeem points, order history, storefront, festive/physical gifts
  socials/                    # Social intranet, townhall, groups, celebrations, wish board, directory
  surveys/                    # Action plan
demo-library/                 # Demo videos and walkthroughs for all features
images/                       # Static assets (SVGs, screenshots)
videos/                       # Video assets
articles/                     # Legacy content — excluded from build via .mintignore
admins/                       # Old folder — excluded from build via .mintignore

Development commands

Run these from the repository root:

# Install Mintlify CLI (once)
npm i -g mint

# Local preview at http://localhost:3000
mint dev

# Check for broken internal links
mint broken-links

# Update CLI to latest version
mint update

Page format

Every page is an .mdx file with YAML frontmatter:

---
title: "Page Title"
description: "One-sentence summary shown in search and meta tags."
---

Pages use Mintlify MDX components (<Card>, <CardGroup>, <Steps>, <Step>, <Tabs>, <Tab>, <Accordion>, etc.). Refer to the Mintlify docs for the full component reference. To install the Mintlify skill for AI-assisted writing:

npx skills add https://mintlify.com/docs

The site has two audience tabs declared in docs.json → navigation.tabs:

Employees — end-user guides (login, profile, social, redeeming points, recognising peers)
Admin — Super Admin / admin guides (programs, billing, surveys, AI, integrations, SSO, security)

Each tab contains named groups, and groups can be nested (e.g. Socials → Groups has its own icon and child pages). The folder structure maps directly to tabs: files under employees/ go in the Employees tab, files under admin/ go in the Admin tab, and files under demo-library/ go in the Demo Library tab. When adding a page, place its .mdx file in the matching directory and add its path to docs.json. To add a new page:

Create the .mdx file in the appropriate directory.
Add its path (without extension) to the correct group under the correct tab in docs.json.

Pages not listed in docs.json will not appear in the sidebar.

Product terminology

This is the Empuls Help Center — a product by Xoxoday. Use these terms consistently:

Empuls — the product name (never “empuls” lowercase)
Super Admin — the highest admin role (capitalised as shown)
reward points — currency employees earn and redeem
awards — the recognition mechanism (spot, approval-based, jury, incentive)
nominations — the submission step in approval/jury award flows

Writing style

Taken from AGENTS.md and CONTRIBUTING.md:

Active voice, second person (“you”)
One idea per sentence; lead with the goal
Sentence case for headings
Bold for UI element labels: Click Settings
Code formatting for file names, commands, paths, and inline code references
Don’t alternate between synonyms for the same concept — pick one term and stick with it

Files excluded from the build

Mintlify auto-ignores .git, .github, .claude, .agents, .idea, node_modules, and top-level README.md / LICENSE.md / CHANGELOG.md / CONTRIBUTING.md. Project-specific excludes in .mintignore:

drafts/ — work-in-progress pages
*.draft.mdx — any file with the draft extension, anywhere in the tree
articles/ — legacy .md files with raw HTML; excluded to prevent MDX parse errors
admins/ — old folder superseded by admin/; excluded to avoid orphaned-page warnings

Use drafts/ or the *.draft.mdx pattern for in-progress content rather than leaving it in docs.json-listed paths.

Publishing

Push to the default branch (main) — the Mintlify GitHub app auto-deploys to production. No build step is required locally beyond mint dev for preview.

​CLAUDE.md

​Repository layout

​Development commands

​Page format

​Navigation

​Product terminology

​Writing style

​Files excluded from the build

​Publishing