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

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

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