shaon

Shaon

Claude Code skill for the shaon repo and binary.

Tool Selection

Prefer the MCP server when a tool already covers the domain operation.
Fall back to the CLI for local-machine or interactive operations: auth, payroll payslip view, reports show, cache refresh attendance-types, serve, and completions.
Use this skill to pick the right surface, the right command/tool, and the right safety flow.

Human-attested writes

All write commands (attendance report today/day/range, attendance auto-fill, attendance resolve) submit under the user's identity against their real employer's system. When driving these, ALWAYS:

Run with --dry-run (the default) first.
Show the resulting preview to the user.
Require the user to explicitly confirm in the conversation before rerunning with --execute.

Never autonomously rerun a write with --execute. Writes must be treated as user-authorized actions and must not be submitted without explicit user confirmation.

CLI Entry Point

If working from a repo checkout, prefer:

scripts/run.sh <command> [args]

If installed globally:

shaon <command> [args]

First-Time Setup

Create ~/.shaon/config.toml:

subdomain = "mycompany"
username = "123456789"
payslip_folder = "/path/to/payslips"   # optional
payslip_format = "%Y-%m.pdf"           # optional

Then authenticate:

shaon auth

If stored credentials are stale and you want a deterministic refresh prompt:

shaon auth --force-prompt

Pick The Right Read Command

User intent	Use
"what's my current month state?"	`shaon attendance overview --json`
"show me the raw calendar / what did Hilan record per day?"	`shaon attendance status --month YYYY-MM`
"what errors do I need to fix?"	`shaon attendance errors --month YYYY-MM`
"what attendance types can I report?"	`shaon attendance types`
"what absence symbols mean?"	`shaon attendance absences`
"show the analyzed hours sheet"	`shaon reports sheet`
"show the manual correction log / audit trail"	`shaon reports corrections`
"show a named Hilan report page"	`shaon reports show <name>`
"download my payslip"	`shaon payroll payslip download --month YYYY-MM`
"open my payslip locally"	`shaon payroll payslip view --month YYYY-MM`
"how much did I earn recently?"	`shaon payroll salary --months N`

attendance overview is usually the best first move for an agent because it bundles identity, summary, errors, missing days, and suggested actions.

JSON contract notes:

attendance status --json returns { month, employee_id, days[] } with day_name, entry_time, exit_time, attendance_type, total_hours, has_error, error_message, and source.
attendance overview --json returns missing_days as { date, day_name } objects.
suggested_actions is keyed by kind; fields are top-level, not nested inside a generic params object.
attendance overview --json --detailed adds a days[] array using the same schema as attendance status --json.

Write Commands

Explicit reporting

Intent	Command
clock in now	`shaon attendance report today --in`
clock out now	`shaon attendance report today --out`
report one explicit day	`shaon attendance report day YYYY-MM-DD --type "regular" --hours 09:00-18:00`
report a range	`shaon attendance report range --from YYYY-MM-DD --to YYYY-MM-DD --type "regular" --hours 09:00-18:00`
auto-fill missing days in a month	`shaon attendance auto-fill --month YYYY-MM --type "regular" --hours 09:00-18:00`
resolve an existing error day	`shaon attendance resolve YYYY-MM-DD --type "regular" --hours 09:00-18:00`

Safety Model

Every write is preview-only by default.
The agent should show the preview summary to the user before rerunning with --execute or execute: true.
The agent must wait for explicit user confirmation before any live submit.
attendance report range and attendance auto-fill skip Fri/Sat unless explicitly overridden.
attendance auto-fill is capped at --max-days 10 by default to prevent accidental bulk edits.

MCP Coverage

Current MCP tools cover:

shaon_status
shaon_errors
shaon_types
shaon_clock_in
shaon_clock_out
shaon_fill
shaon_auto_fill
shaon_resolve
shaon_payslip_download
shaon_salary
shaon_sheet
shaon_corrections
shaon_absences
shaon_overview

CLI-only features:

shaon auth
shaon payroll payslip view
shaon reports show <name>
shaon cache refresh attendance-types
shaon serve
shaon completions

Agent Workflows

Review the month first

shaon attendance overview --json

Fix an attendance error safely

shaon attendance errors --month 2026-04 --json
shaon attendance resolve 2026-04-09 --type "regular" --hours 09:00-18:00
# After explicit user confirmation:
shaon attendance resolve 2026-04-09 --type "regular" --hours 09:00-18:00 --execute

Fill a missing range safely

shaon attendance report range --from 2026-04-01 --to 2026-04-05 --type "regular" --hours 09:00-18:00
# After explicit user confirmation:
shaon attendance report range --from 2026-04-01 --to 2026-04-05 --type "regular" --hours 09:00-18:00 --execute

Hebrew payslip workflow

shaon payroll payslip download --month 2026-03
shaon payroll payslip view --month 2026-03

Sensitive recovery command

shaon payroll payslip password --force-sensitive-output prints the current Hilan account password in plaintext to standard output. It does not recover historical passwords used for PDFs encrypted before a password change. Output may be captured by shells, terminals, logs, remote sessions, screenshots, and agent transcripts. Run it only on a private interactive terminal you control.

Troubleshooting

CAPTCHA: the user must solve it in the browser first.
Type resolution fails: run shaon cache refresh attendance-types or pass the numeric type code directly.
Session expired or stale stored credentials: rerun shaon auth --force-prompt to verify and replace the stored password.

About this skill