# Decky agent notes

## Project

- The active app is `app/`: Tauri 2 + Svelte 5 + TypeScript. The older .NET
  projects under `src/` and `tests/` are reference code, not the product.
- Decky is a compact, Nextcloud-inspired desktop client for Nextcloud Deck.
  Preserve its dark native title bar, horizontal/vertical views, drag-and-drop,
  compact cards, collapsible sidebar, and footer-free layout.
- Background sync begins after 10 seconds idle and repeats every 30 seconds. It
  must pause during edits, drags, loading, modals, and while the window is hidden.
- Never store or commit Nextcloud credentials. Use an app password and the OS
  credential store. Live-instance tests require the user to enter credentials.

## Nextcloud API compatibility

- Client code and tests are in `app/src/lib/deck-api.ts` and
  `app/src/lib/deck-api.test.ts`.
- Support both documented `index.php/apps/deck/api/v1.0/` and rewrite-friendly
  `apps/deck/api/v1.0/` paths.
- Preserve complete card fields on updates, including color and object/string
  owner handling. Keep the tested cross-stack card-move fallback.
- Stack reorder uses Deck's OCS reorder endpoint and verifies persisted order.
- Respect board permissions before exposing edit/manage/delete controls.

## Validation

From `app/`, run `npm ci`, `npm run check`, `npm test`, and `npm run build`.
Build Windows installers on this Windows machine; the Unraid Forgejo Docker
runner only validates the web client via `.forgejo/workflows/validate.yml`.

## Versions and releases

- Installed apps update from signed Forgejo Release assets, never from Git.
- A released version/tag is immutable. Always increment the semantic version;
  never republish or replace assets for an existing version.
- Use `scripts/Set-Version.ps1` to synchronize npm, Cargo, Tauri, and the browser
  fallback. Commit and push source to `main` before publishing the release.
- Build/sign with `scripts/Prepare-Release.ps1`. Generated files live under
  `artifacts/release/vX.Y.Z/` and stay out of Git.
- Publish by double-clicking `scripts/Publish-DeckyRelease.cmd` or by invoking
  `scripts/Publish-ForgejoRelease.ps1`. The publisher creates the tag/release,
  uploads the installer/signature, commits `releases/latest.json` to `main`, and
  automatically fast-forwards the local checkout to that metadata commit.
- The publisher requires a clean `main` that exactly matches `origin/main`, so
  commit and push source first. LF-to-CRLF messages on Windows are warnings,
  not failures.
- Forgejo: `https://git.elijahkuntz.com/Elijah/Decky`. A publishing PAT needs
  `write:repository`; never commit or print it.
- The permanent Tauri updater key is outside the repository at
  `%USERPROFILE%\.tauri\decky.key` with its password beside it. Never expose,
  replace, or regenerate this key after releases have shipped.

See `app/UPDATES.md` for the complete release procedure.