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:

1. Run with --dry-run (the default) first.
2. Show the resulting preview to the user.
3. 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.

Further Reading

• README.md
• ARCHITECTURE.md
• PROTOCOL.md