schema_version: '0.7'

intent: >
  GitHub Actions workflows and Dependabot configuration for NotarAI. CI runs
  on every PR and push to main; docs are deployed to GitHub Pages on every
  push that touches docs/ or notarai.spec.json; cross-platform release
  binaries are built and published to GitHub Releases and crates.io on every
  GitHub release. Dependabot keeps GitHub Actions and Cargo dependency
  versions current.

behaviors:
  - name: ci_on_push_and_pr
    given: 'a push to main or a pull request targeting main'
    then: 'the CI workflow runs three parallel jobs — fmt (cargo fmt --check), clippy (cargo clippy -- -D warnings), and test (cargo test, which implicitly builds); the test job requires fmt and clippy to pass first'

  - name: docs_deploy_on_push
    given: 'a push to main that touches any file under docs/ or notarai.spec.json'
    then: 'the docs workflow installs mdbook and mdbook-mermaid via cargo, builds the book, copies the mdBook output into public/docs/, adds a redirect at public/index.html, copies each schemas/<version>/spec.schema.json to public/schema/<version>/spec.schema.json (frozen snapshots for 0.5 and 0.6) and copies notarai.spec.json to public/schema/0.7/spec.schema.json, and deploys the public/ directory to GitHub Pages; only one deploy runs at a time (cancel-in-progress)'

  - name: init_sync_check
    given: 'the test job passes on a push to main or a PR targeting main'
    then: 'the init-sync job builds the release binary, runs notarai init, then checks git diff --exit-code .claude/commands/ to ensure the installed commands match the binary-embedded content; fails if any drift is detected'

  - name: release_on_tag
    given: 'a GitHub release is published'
    then: 'the release workflow builds cross-platform binaries via cargo-zigbuild for 7 targets (x86_64/aarch64 linux-gnu, x86_64/aarch64 linux-musl, x86_64/aarch64 macos, x86_64 windows-gnu), uploads them as release assets, and publishes the crate to crates.io'

  - name: dependabot_updates
    given: 'a new version of a GitHub Actions action, Cargo dependency, or npm dependency is available'
    then: 'Dependabot opens a PR to update the pinned version'

constraints:
  - 'Release binaries are cross-compiled on ubuntu-latest using cargo-zigbuild for all 7 targets'
  - 'Crates.io publish uses CARGO_REGISTRY_TOKEN secret'
  - 'Docs deployment targets the github-pages environment and requires pages write + id-token write permissions'
  - 'CI must pass cargo fmt, clippy, and all tests before merge'

invariants:
  - 'A release binary must never be published without a successful build and test run'

artifacts:
  configs:
    - path: '.github/workflows/ci.yml'
      role: 'CI workflow — build + test + fmt + clippy on push and PR'
    - path: '.github/workflows/docs.yml'
      role: 'Docs deploy workflow -- mdBook build + schema copy + GitHub Pages deploy on docs/ changes'
    - path: '.github/workflows/release.yml'
      role: 'Release workflow — cargo-zigbuild cross-compile + GitHub Releases + crates.io publish'
    - path: '.github/dependabot.yml'
      role: 'Dependabot config for keeping GitHub Actions and Cargo dependency versions current'

decisions:
  - date: '2026-02-23'
    choice: 'cargo-zigbuild for cross-compilation on ubuntu-latest'
    rationale: 'All 7 targets (including macOS and Windows) build on a single ubuntu-latest runner without needing native macOS/Windows runners, reducing CI cost and complexity'
  - date: '2026-02-23'
    choice: 'Dual distribution: GitHub Releases + crates.io'
    rationale: 'GitHub Releases provides direct binary downloads for users without Rust; crates.io serves Rust users who prefer cargo install'
  - date: '2026-02-26'
    choice: 'init-sync CI job to catch command drift'
    rationale: 'notarai init always overwrites .claude/commands/ from embedded binary content; the CI job verifies that the checked-in .claude/commands/ files match by running init and checking for a clean git diff'
  - date: '2026-02-26'
    choice: 'Migrate docs from Astro/Starlight to mdBook'
    rationale: 'mdBook is simpler and lighter -- no Node.js ecosystem, no build pipeline, no workspace dependencies. The CI docs job is now a single cargo install + mdbook build step instead of a multi-step npm/Astro pipeline'
