shaon: Instructions file for Claude Code

CLAUDE.md

This file is for coding agents and maintainers working in this repository.

Read This First

• README.md: user-facing install and usage
• ARCHITECTURE.md: crate boundaries and maintenance map
• PROTOCOL.md: Hilanet wire behavior and replay details
• skills/shaon/SKILL.md: Claude Code skill text

Do not duplicate hard-coded command or tool counts in docs unless the count itself matters. The authoritative user-facing surfaces are:

• CLI subcommands: crates/shaon-cli/src/lib.rs
• MCP tools: crates/shaon-mcp/src/lib.rs
• Claude Code plugin metadata: .claude-plugin/plugin.json
• Claude Code skill text: skills/shaon/SKILL.md

What This Repo Is

Rust workspace for automating Hilan / Hilanet through:

1. a human-facing CLI
2. a stdio MCP server
3. a Claude Code plugin / skill

The protocol has two layers:

1. ASP.NET WebForms (.aspx) for calendar pages, error-fix flows, and classic reports
2. ASMX JSON endpoints (/Services/Public/WS/*.asmx/*) for bootstrap, absences, tasks, and salary data

Build and Checks

cargo build -p shaon --release
cargo test --workspace --all-targets
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
scripts/run.sh <subcommand> [args]

Rust requirement: 1.80+.

Release

Release Contract

• Release from main only through ./scripts/release.sh X.Y.Z and the resulting release PR; do not create manual tags or GitHub releases.
• Keep one version across CHANGELOG.md, workspace metadata, skill frontmatter, and plugin manifests.
• The release PR merge is the trigger. CI validates the merged chore(release): vX.Y.Z commit, creates the matching tag, publishes the GitHub release from the committed changelog entry, and then opens gh-driven PRs to update Homebrew and Scoop.
• GitHub Actions workflow permissions for this repo must stay on Read and write, and RELEASE_GITHUB_TOKEN should be configured; the release workflow publishes the GitHub release with gh.
• macOS release binaries are signed with a Developer ID and notarized by scripts/codesign-macos.sh when these repository secrets are set: APPLE_TEAM_ID, APPLE_DEVELOPER_ID_P12_BASE64 (base64 of a .p12 with the "Developer ID Application" certificate, its key and the Developer ID intermediate), APPLE_DEVELOPER_ID_P12_PASSWORD, APPLE_NOTARY_ISSUER_ID, APPLE_NOTARY_KEY_ID, and APPLE_NOTARY_KEY_P8_BASE64 (base64 of an App Store Connect API key .p8). Set all six or none: with none, the release warns and signs ad-hoc; with some, it fails. Ad-hoc binaries get a new Keychain partition ID (cdhash:) per build, so users approve Keychain access again after each upgrade; Developer ID binaries share one teamid: partition ID. Keep the identifier io.github.avivsinai.shaon: a changed identifier or team makes every user approve again.
• skills-marketplace is a registry pointer to this repo's default branch. Once shaon is listed there, marketplace installs track main; no separate marketplace release job is required for day-to-day skill changes.