diff --git a/ACKNOWLEDGEMENTS.md b/ACKNOWLEDGEMENTS.md index f5c5cb5..daada9e 100644 --- a/ACKNOWLEDGEMENTS.md +++ b/ACKNOWLEDGEMENTS.md @@ -1,6 +1,6 @@ # Acknowledgements -Klicky began as a Linux-focused evolution of [Sauhard74/klicky](https://github.com/Sauhard74/klicky), created by Sauhard Gupta. +I started Klicky after seeing [Sauhard Gupta's original macOS project](https://github.com/Sauhard74/klicky) running on a Mac and wanting it on my Omarchy machine. The original project established the core ideas that remain central here: @@ -16,7 +16,7 @@ This repository preserves the original Git history and MIT license. The original ## Linux and cross-platform work -The current repository adds and maintains: +I expanded it to Linux and Windows, with help from contributors. The main additions include: - Direct Linux `evdev` input - Wayland and X11 independence @@ -26,8 +26,9 @@ The current repository adds and maintains: - Configurable low-latency buffer fallbacks - Capped per-key loudness normalization - Linux udev and systemd integration -- Omarchy Quickshell integration -- Linux and macOS CI +- Native Windows input, audio and tray controls +- macOS menu controls and Omarchy Klicky Bar +- Cross-platform installers, packages and CI - Hardware-backed Linux benchmarks and documentation ## Related projects @@ -45,7 +46,7 @@ Contributors adding or replacing sounds must provide a clear source and redistri ## Visual identity and typography -The Klicky mascot identity and selected cozy keyboard artwork establish the project's visual direction. The public asset library contains selected final illustrations and simplified application marks; private reference boards are not distributed. +The Klicky mascot identity and selected cozy keyboard artwork establish the project's visual direction. The [asset library](assets/branding) contains the final illustrations and application marks. The website and outlined wordmarks use Nunito by The Nunito Project Authors. The typeface and web subset retain the [SIL Open Font License](assets/website/fonts/OFL.txt), separately from Klicky's MIT-licensed application code. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 4ad0b7c..05a4b8d 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -47,7 +47,7 @@ We agree to restrict the following behaviors in our community. Instances, threat Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm. -When an incident does occur, it is important to report it promptly. To report a possible violation, **email Muneer Alam at [muneer.alam320@gmail.com](mailto:muneer.alam320@gmail.com). Please include relevant links, what happened and how you can be contacted. Keep reports out of public issues and discussions.** +When an incident does occur, it is important to report it promptly. To report a possible violation, **email me at [muneer.alam320@gmail.com](mailto:muneer.alam320@gmail.com). Please include relevant links, what happened and how you can be contacted. Keep reports out of public issues and discussions.** Project Maintainers take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Project Maintainers will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution. @@ -77,7 +77,7 @@ If an investigation by the Project Maintainers finds that this Code of Conduct h This enforcement ladder is intended as a guideline. It does not limit the ability of Project Maintainers to use their discretion and judgment, in keeping with the best interests of our community. -For Klicky, Muneer Alam handles reports and moderation. Reports are handled privately, with information shared only as needed to investigate and respond. Please use [private security reporting](https://github.com/Muneer320/klicky/security/advisories/new) for software vulnerabilities. +I handle reports and moderation for Klicky. Reports are handled privately, with information shared only as needed to investigate and respond. Please use [private security reporting](https://github.com/Muneer320/klicky/security/advisories/new) for software vulnerabilities. ## Scope diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dca4e9c..2f7537a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ Thank you for helping improve Klicky. Small, focused changes are easier to test across input stacks and operating systems than broad rewrites. -New to the product? Start with the [field guide](https://klicky.muneer320.tech/guide.html). For presentation work, use the [character story](docs/CHARACTER.md) and [brand asset guide](docs/BRANDING.md); keep instructions technically clear and the mascot recognizable. +New to the product? Start with the [field guide](https://klicky.muneer320.tech/guide.html). For presentation work, use the [character story](docs/CHARACTER.md) and [artwork and export instructions](docs/WEBSITE.md#artwork); keep instructions technically clear and the mascot recognizable. For usage questions, try [Discussions Q&A](https://github.com/Muneer320/klicky/discussions/categories/q-a). Use [Ideas](https://github.com/Muneer320/klicky/discussions/categories/ideas) to discuss a proposal before turning it into an implementation issue. The [wiki](https://github.com/Muneer320/klicky/wiki) links to the maintained platform guides. @@ -128,24 +128,7 @@ same direct `swiftc` build as the menu installer, without installing or running the app. The workflow verifies that `KlickyMenu.swift` is in the extracted source archive and retains SARIF results as short-lived CI artifacts. -Until the repository variable `CODEQL_ADVANCED_ENABLED` is `true`, analysis runs -without uploading results; the existing default setup continues to publish its -scans. Do not enable uploads while default setup is active. - -For maintainers switching to advanced setup: - -1. Review the workflow and verify successful extraction/analysis for all five - languages on the intended commit. Keep default setup active during validation. -2. After merging, switch CodeQL from default to advanced setup, set - `CODEQL_ADVANCED_ENABLED=true`, and run **CodeQL advanced** on `master`. -3. Verify all five uploaded language results and a PR comparison, including a - Dependabot update. Check that existing alert dispositions are preserved. Only - then retire obsolete default configurations or change required-check names. -4. To roll back, set the variable to `false` before restoring default setup with - its previous language selection. Keep normal CI and scanning requirements in - place throughout the transition. - -GitHub [rejects advanced CodeQL uploads while default setup is enabled](https://docs.github.com/en/code-security/reference/code-scanning/sarif-files/troubleshoot-sarif-uploads/default-setup-enabled). +CodeQL uses the advanced workflow. `CODEQL_ADVANCED_ENABLED` controls SARIF uploads; keep a single active upload configuration. GitHub [rejects advanced uploads while default setup is enabled](https://docs.github.com/en/code-security/reference/code-scanning/sarif-files/troubleshoot-sarif-uploads/default-setup-enabled). ## Commits diff --git a/README.md b/README.md index d863a35..58e16ab 100644 --- a/README.md +++ b/README.md @@ -223,12 +223,13 @@ Klicky uses native keyboard input on each OS and prepares audio before you type. | I want to… | Start here | |---|---| | Install, configure or troubleshoot | [The website field guide](https://klicky.muneer320.tech/guide.html) | +| Browse all guides | [Documentation index](docs/README.md) | | Look up commands or configuration | [CLI](docs/CLI.md) · [Configuration](docs/CONFIGURATION.md) | | Add recordings or desktop integration | [Sound packs](docs/SOUND_PACKS.md) · [Omarchy](docs/OMARCHY.md) | | Understand or contribute code | [Build, test and contribute](CONTRIBUTING.md) · [Open issues](https://github.com/Muneer320/klicky/issues) | -| Explore the character or use artwork | [Klicky's story](docs/CHARACTER.md) · [Brand assets](docs/BRANDING.md) | +| Explore the character or use artwork | [Klicky's story](docs/CHARACTER.md) · [Artwork](assets/branding) | | Check releases and project history | [Releases](https://github.com/Muneer320/klicky/releases) · [Changelog](CHANGELOG.md) | -Klicky grew from [Sauhard Gupta's original macOS project](https://github.com/Sauhard74/klicky). After seeing it on a Mac, [Muneer Alam](https://muneer320.tech/) wanted it on his Omarchy machine, adapted it for Linux, and kept going until Windows joined in. [Read the development story.](https://muneer320.tech/projects/klicky/) +I first saw [Sauhard Gupta's original macOS project](https://github.com/Sauhard74/klicky) running on a Mac and wanted it on my Omarchy machine. So I adapted it for Linux, then kept going until Windows joined in. [Read the development story.](https://muneer320.tech/projects/klicky/) · [About me](https://muneer320.tech/) [MIT license](LICENSE) · [Acknowledgements and third-party credits](ACKNOWLEDGEMENTS.md). Third-party notices are included with packaged downloads. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0ef77e9..bb0e887 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -185,9 +185,7 @@ Windows EXE/ZIP installations store configuration/custom packs under `%LOCALAPPD - Linux input devices are discovered at daemon startup. A newly added keyboard requires a daemon restart, while a lost reader causes a systemd-managed process to restart and rediscover devices. - Linux/macOS physical audio-device replacement and suspend/resume need additional runtime testing after the Rodio 0.22 migration. Windows implements recovery, with its hardware matrix still under qualification. - Benchmark mode measures input callback to mixer dispatch, not microphone-observed audible latency. -- Windows support targets Windows 11 x64 interactive desktops. Windows 10, ARM64, remote sessions and secure desktops are outside the initial support scope. See the [measurement guide](BENCHMARKS.md) for the distinction between internal timing and audible latency. - -These constraints are intentionally explicit. They should become focused issues rather than hidden claims of universal support. +- Windows support targets Windows 11 x64 interactive desktops. Windows 10, ARM64, remote sessions and secure desktops are outside the supported desktop scope. See the [measurement guide](BENCHMARKS.md) for the distinction between internal timing and audible latency. ## Further reading diff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.md index 1fa88e0..2dc9aaf 100644 --- a/docs/BENCHMARKS.md +++ b/docs/BENCHMARKS.md @@ -8,9 +8,9 @@ klicky start --benchmark On Linux/macOS, each mapped keypress prints the elapsed time between the platform input callback and the call that adds the cached audio source to the persistent mixer. Windows prints aggregate diagnostics at exit without key names. Neither mode measures physical key actuation, device scheduling, DAC or speaker onset. -Windows has no calibrated physical-to-audible result established by these figures. Preserve matched keyboard/output/measurement conditions when comparing platforms; requested buffer sizes, dispatch timings and subjective listening are separate evidence. Qualification tooling is documented in [the bounded harness guide](../tools/windows-qualification/USAGE.md). +To measure physical-to-audible latency, record the key impact and generated sound on the same timeline, with matched hardware and output routes. The [bounded qualification harness](../tools/windows-qualification/USAGE.md) supports this work; its internal dispatch counters are a separate measurement. -## Current Linux result +## Recorded Linux run Test environment: @@ -81,18 +81,6 @@ The original `eg-oreo` key slices were much quieter than several Cherry MX packs For comparison, `cherrymx-blue-pbt` KeyA measured -30.7 dB mean and -6.7 dB peak. Klicky now normalizes each quiet key slice once at startup, targeting an 85 percent peak with a maximum 6x gain. A real-hardware listening test confirmed improved volume without audible clipping. -## What these numbers do not prove - -Input-to-dispatch timing excludes: - -- Kernel and hardware time before the callback -- Audio buffer duration -- PipeWire or CoreAudio scheduling -- DAC conversion -- Speaker propagation - -A rigorous physical-to-audible test requires an external microphone or loopback setup that records the physical key impact and generated sound on one timeline. Until that test exists, Klicky reports dispatch and negotiated buffer measurements separately. - ## Reproducing the dispatch test 1. Install and start Klicky normally once. diff --git a/docs/BRANDING.md b/docs/BRANDING.md deleted file mode 100644 index 7c6a3fd..0000000 --- a/docs/BRANDING.md +++ /dev/null @@ -1,65 +0,0 @@ -# Klicky brand assets - -**There's someone under your keys.** - -Klicky is the tiny fictional creature behind the keyboard-sound app. Its warm cream body, broad violet sound-wave ears, three forehead keycaps and curled antenna are the recognizable anchors. Keep them consistent across detailed illustrations and small icons. [Read the character story](CHARACTER.md). - -## Asset library - -| Asset | Use | -|---|---| -| [Colour mark](../assets/branding/klicky.svg) / [512px PNG](../assets/branding/klicky.png) | Website navigation, documentation, app identity | -| [Monochrome mark](../assets/branding/klicky-monochrome.svg) | Single-colour artwork; uses `currentColor` | -| [Light-surface lockup](../assets/branding/klicky-lockup.svg) / [dark-surface lockup](../assets/branding/klicky-lockup-dark.svg) | Mascot + name | -| [Wordmark](../assets/branding/klicky-wordmark.svg) / [dark-surface wordmark](../assets/branding/klicky-wordmark-dark.svg) | Name without the mascot | -| [Happy mascot](../assets/branding/mascot-happy.png) / [resting mascot](../assets/branding/mascot-resting.png) | Transparent illustrations | -| [Under the keys](../assets/branding/under-the-keys.png) | Keyboard-world illustration | -| [Social preview JPEG](../assets/branding/social-preview.jpg) | Preferred GitHub upload: **1280 × 640, under 1 MB** | -| [Social preview PNG](../assets/branding/social-preview.png) | Compatibility version, also 1280 × 640 and under 1 MB | -| [Sound demo MP4](../assets/website/demo/klicky-demo.mp4) / [watch online](https://klicky.muneer320.tech/#demo) | 45 seconds, 1920 × 1080, about 2.6 MB; character, three packs and all three operating systems | -| [Demo poster](../assets/website/demo/klicky-demo-poster.jpg) / [English captions](../assets/website/demo/klicky-demo.en.vtt) | Thumbnail and accessible captions for the sound demo | -| [Menu template](../assets/branding/klicky-menu-template.png) / [2x](../assets/branding/klicky-menu-template@2x.png) | 18/36px macOS template assets | -| [Windows ICO](../packaging/windows/klicky.ico) | Executable, tray and installer; nine sizes from 16 to 256px | - -The final illustrations were prepared from the established character references. The social poster uses the selected cozy keyboard artwork. Original reference boards and internal character briefs are not public project assets. - -The sound demo is click-to-play with no background music. When sharing it, include its [asset credits](../assets/website/demo/CREDITS.md), which cover the sound recordings, Nunito and the platform icons. Use the demo poster for the video; keep the cozy artwork as the repository's social preview. - -## Colour and type - -| Role | Colour | -|---|---| -| Cream | `#FFF3E6` | -| Deep plum | `#21152F` | -| Violet | `#7435B4` | -| Lilac | `#C084FC` | -| Blush | `#FFB3C3` | -| Honey | `#FFD76A` | - -The website uses locally hosted **Nunito**, with system sans-serif fallbacks and system monospace for commands. No font-service request is needed. Nunito is distributed under its [SIL Open Font License](../assets/website/fonts/OFL.txt); the original font and Latin web subset are committed. Wordmark lettering is outlined, so it does not require installed fonts. - -Use plum/cream for reading surfaces, violet for controls and honey sparingly for sound and emphasis. Check contrast in both light and dark appearances; the decorative palette does not replace accessible text colours. - -## Usage - -- Leave clear space around the curl and ears; do not squash, crop or stretch the mark. -- Use the simplified mark for small application icons; do not reduce a detailed illustration into an unreadable tray image. -- Let the monochrome template inherit the platform's appearance. Do not derive it by recolouring the detailed artwork. -- Keep the creature curious, cheerful and unhurried. Resting is content, not a request to keep typing. -- Do not establish a species/origin, add unrelated costumes or imply an AI companion, virtual pet or gamification feature. -- Keep documentation and error messages clear. Personality belongs around instructions, never in place of an actionable explanation. - -## Platform exports - -```sh -npm ci --prefix tools/branding --ignore-scripts -npm run --prefix tools/branding build -``` - -The locked resvg renderer exports the colour SVG to PNG/ICO and the independently authored monochrome SVG to macOS templates. Cargo consumes committed files; users need neither Node nor an image renderer. CI checks that regenerated native assets match Git. - -Illustrations and the selected social JPEG/PNG are curated final raster assets, not regenerated by the vector exporter. Keep both poster formats at exactly 1280 × 640 and below 1,000,000 bytes. Optimized website illustrations live under `assets/website/mascot`; their PNG masters stay in the public asset library. - -New icons appear in newly built app packages. Replacing repository artwork does not update an already-installed executable or authorize a release. - -Upload `assets/branding/social-preview.jpg` in GitHub **Settings → Social preview**. The Pages builder publishes the artwork for website sharing; the GitHub repository setting is separate. diff --git a/docs/CHARACTER.md b/docs/CHARACTER.md index 7d921dc..6bf325d 100644 --- a/docs/CHARACTER.md +++ b/docs/CHARACTER.md @@ -18,8 +18,6 @@ And when you stop? Klicky settles down. A little quiet is good, too. Klicky is curious, cheerful, affectionate and a little mischievous. It is never needy: no guilt for taking breaks, no demand to keep typing. Its species, age, origins and wider world stay deliberately unexplained. -The visual anchors are its warm cream body, broad violet ears carrying sound bars, three little forehead keycaps and curled antenna. Those features should remain recognizable in a detailed illustration or a simple monochrome icon. - The mascot is a fictional brand character. The app is a local Rust keyboard-sound utility, with no AI companion, virtual-pet simulation, streaks or rewards. -For the actual software, start with the [field guide](https://klicky.muneer320.tech/guide.html). For artwork and visual consistency, see the [brand guide](BRANDING.md). +For the actual software, start with the [field guide](https://klicky.muneer320.tech/guide.html). For artwork, browse the [asset library](../assets/branding). diff --git a/docs/MAINTAINING_APT.md b/docs/MAINTAINING_APT.md index a732b77..df57b93 100644 --- a/docs/MAINTAINING_APT.md +++ b/docs/MAINTAINING_APT.md @@ -42,13 +42,13 @@ Never commit private keys, passphrases, or revocation certificates. [The APT workflow](../.github/workflows/apt-repository.yml) publishes through the existing GitHub Pages artifact and deploy job. It runs for a published stable GitHub release, a manual dispatch, or a push to the workflow's listed `master` paths (including the website, public media and install/uninstall scripts). Its release-event path excludes drafts and prereleases. For manual dispatch, choose an already published stable release: the job validates the numeric tag and assets without independently rechecking its draft/prerelease flags. Pull requests do not receive signing secrets or deploy. -**Build, release publication and APT promotion are separate steps.** [The release workflow](../.github/workflows/release.yml) produces an Actions candidate artifact; it does not publish a GitHub release. After the [release checks and approval](RELEASE_READINESS.md), publish the stable release with its verified assets. That publication can trigger APT. If publication uses `GITHUB_TOKEN`, GitHub suppresses the subsequent release-event workflow, so dispatch APT manually. See [GitHub's workflow-trigger rules](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow). +**Build, release publication and APT promotion are separate steps.** [The release workflow](../.github/workflows/release.yml) produces an Actions candidate artifact; it does not publish a GitHub release. After the [release checklist](PACKAGING.md#release-checklist), publish the stable release with its verified assets. That publication can trigger APT. If publication uses `GITHUB_TOKEN`, GitHub suppresses the subsequent release-event workflow, so dispatch APT manually. See [GitHub's workflow-trigger rules](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow). The current `github-pages` environment permits deployments from `master` and `gh-pages`, not version tags. A release-event run can build the signed archive successfully and still be refused at deployment. For a release, use the manual dispatch on `master` below and verify its deploy job succeeds. Keep the environment protections in place. The release tag is resolved from the release event for `release: published`, from the required `tag` input for a manual dispatch, and from GitHub's latest non-draft, non-prerelease release for a qualifying push to `master`. The selected source version must match that tag. A push ahead of the latest release preserves the current site; a mismatched manual/release request fails. Once matched, the workflow downloads the `.deb` and `SHA256SUMS` for that exact tag, requires exactly one amd64 package and exactly one checksum entry for it, verifies the checksum, and checks that its Debian version matches the tag. -After the approved stable GitHub release is published with its `.deb` and `SHA256SUMS`, dispatch APT publication from the permitted branch: +After the stable GitHub release is published with its `.deb` and `SHA256SUMS`, dispatch APT publication from the permitted branch: ```bash gh workflow run apt-repository.yml --repo Muneer320/klicky \ diff --git a/docs/PACKAGING.md b/docs/PACKAGING.md index 34a0db7..52c2dcc 100644 --- a/docs/PACKAGING.md +++ b/docs/PACKAGING.md @@ -109,17 +109,45 @@ The workflow: 2. Runs Linux/macOS and Windows checks, including native macOS lifecycle validation. 3. Builds and inspects Debian/Arch packages and the Windows installer/portable ZIP. 4. Verifies build identity, asset inventory and sidecars, then generates the release manifest and `SHA256SUMS`. -5. Uploads a combined candidate artifact for review. Publication requires explicit approval and a separate action; no release is automatically published. +5. Uploads a combined candidate artifact for review. Release publication is a separate action; this workflow never publishes automatically. The regular package workflow also builds both formats on pushes and pull requests. +## Release checklist + +The [release workflow](../.github/workflows/release.yml) builds a candidate from a branch or version tag. It archives the exact source, builds native packages and records revision/tree, file sizes, hashes and signing status in `RELEASE-MANIFEST.json`. `SHA256SUMS` covers the payloads and manifest. A candidate run does not publish a GitHub release or deploy the site. + +```bash +gh workflow run release.yml --ref REVIEWED_BRANCH +gh run list --workflow release.yml +gh run download RUN_ID --name klicky-VERSION-release-candidate --dir target/release-candidate +``` + +Replace the branch, run ID and version with the candidate being reviewed. The payload set includes Debian and Arch packages, the Windows installer and ZIP, source archive and checksum sidecars. + +Before publication: + +1. Keep Cargo/lockfile, Debian/Arch/resource versions, changelog and public download links aligned. Verify the source archive preserves executable script modes. +2. Pass cross-platform CI and package validation. Check bundled sounds, licenses, source obligations, checksums and the recorded source revision/tree. +3. Exercise first install, upgrade, removal and recovery with disposable settings/custom packs. Cover playing, paused and stopped sessions, login startup, data persistence and purge. Windows validation includes missing-CLI recovery, foreign-file refusal and active-bundle interlocks. +4. Check user-facing input/audio behavior on the available desktop hardware. Record listening feedback separately from dispatch or physical latency measurements; state any remaining hardware gaps. +5. Scan the exact Windows release files with current antivirus protection. The release workflow uses a disposable runner to remove inherited scan exclusions, update Defender and scan both original archives and expanded payloads. Missing protection, stale signatures or detections fail assembly. Its `windows-security-evidence` artifact records engine/signature versions and file hashes. This does not sign the standalone files or qualify Windows ARM support. + +To publish, tag the reviewed commit with the version in `Cargo.toml`, build that tag, and verify the final downloaded assets. Publish the GitHub release with its notes, payloads, manifest and checksums. Keep published assets immutable; ship a new version rather than replacing bytes under an existing tag. + +Then follow [APT publication](MAINTAINING_APT.md#publication), retaining all authenticated historical packages. The Pages environment deploys from `master`, not version tags; a workflow-token-created release also needs a manual APT dispatch. Confirm the archive and site deployed before changing installation guidance. A source-version bump ahead of its matching published release leaves the existing site intact. + +After publication, verify public downloads, checksums, install/remove endpoints, signed APT metadata, sound previews and the custom domain. Keep package-manager manifests aligned with the release; advertise a channel only after it is available. + +Microsoft Store updates have a separate build, certification and publication lifecycle. Keep the [package identity/version mapping](WINDOWS_STORE.md#build) stable, validate the exact MSIX, submit accurate capability/listing information and verify the public production package. Store signing does not sign the standalone EXE/ZIP files. + ## APT repository Klicky has a public, signed APT repository at [muneer320.github.io/klicky](https://muneer320.github.io/klicky/), using suite `stable`, component `main`, and architecture `amd64`. Follow the [APT repository guide](APT_REPOSITORY.md) to install through the signed source. Stop the user service before replacing an installed package; the [update guide](INSTALLATION.md#updates-and-removal) includes the commands. Packages contain published release code rather than the current source tree. The archive retains older published packages when adding a release. Use `apt-cache policy klicky` to inspect the available versions and current candidate. The redesigned homepage and installation/removal helpers are live. Use `systemctl --user` for service controls across both retained versions. -[APT publication](MAINTAINING_APT.md#publication) consumes a published release `.deb` and `SHA256SUMS`, retains packages from the live signed index, signs regenerated repository metadata, and deploys the website and archive together to GitHub Pages. First approve and publish the candidate as a stable GitHub release. APT can then run through its release event or manual dispatch. Matching-version pushes to the listed `master` paths also deploy; a version bump ahead of publication leaves the current site intact. If a release is published using `GITHUB_TOKEN`, dispatch APT manually because that token's release event does not start another workflow. +[APT publication](MAINTAINING_APT.md#publication) consumes a published release `.deb` and `SHA256SUMS`, retains packages from the live signed index, signs regenerated repository metadata, and deploys the website and archive together to GitHub Pages. Publish the validated candidate as a stable GitHub release first. APT can then run through its release event or manual dispatch. Matching-version pushes to the listed `master` paths also deploy; a version bump ahead of publication leaves the current site intact. If a release is published using `GITHUB_TOKEN`, dispatch APT manually because that token's release event does not start another workflow. Publication requires the configured signing secrets and GitHub Pages deployment permissions. The workflow stops if it cannot authenticate and recover every package version from the currently published APT index. See the guide for prerequisites, publication steps, test coverage, and key rotation. @@ -134,7 +162,7 @@ Use the [installation guide](INSTALLATION.md) for setup, updates and removal. A | **Microsoft Store** | Published Windows package, with updates delivered through the Store. Follow the [MSIX guide](WINDOWS_STORE.md) when preparing submissions. | | **Homebrew** | [Project tap](https://github.com/Muneer320/homebrew-tap) for Apple Silicon, including sound packs and the menu helper. Keep formula source hashes and lifecycle checks aligned with releases. Intel Macs use the source installer. | | **Scoop** | [Project bucket](https://github.com/Muneer320/scoop-bucket) for Windows. Maintain manifest hashes, version-directory migration and owned startup cleanup. | -| **Omarchy** | Engine [package submission](https://github.com/omacom/omarchy-pkgs/pull/2829) and native [marketplace submission](https://github.com/omacom/omarchy-plugin-marketplace/issues/15124) are under review. Klicky Bar can already be installed directly; see the [Omarchy guide](OMARCHY.md). | +| **Omarchy** | Klicky Bar is available in the [official plugin marketplace](https://plugins.omarchy.org/plugin.html?id=io.github.muneer320.klicky-bar). The engine [package submission](https://github.com/omacom/omarchy-pkgs/pull/2829) is tracked separately; see the [Omarchy guide](OMARCHY.md). | The [distribution tracking issue](https://github.com/Muneer320/klicky/issues/149) records outstanding rollout work. AUR publication remains deferred in [PR #9](https://github.com/Muneer320/klicky/pull/9); the Arch recipe and downloadable package are available independently. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..dceea1e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,39 @@ +# Klicky documentation + +Start with the [project overview](../README.md) or the [visual field guide](https://klicky.muneer320.tech/guide.html). Pick a guide below when you need more detail. + +## Use Klicky + +| I want to… | Read | +|---|---| +| Install, update or uninstall | [Installation](INSTALLATION.md) | +| Find a command | [CLI reference](CLI.md) · [man page](klicky.1) | +| Change settings or find my files | [Configuration](CONFIGURATION.md) | +| Fix sound, permission or startup problems | [Troubleshooting](TROUBLESHOOTING.md) | +| Add or create a sound pack | [Sound packs](SOUND_PACKS.md) | +| Set up Klicky Bar | [Omarchy integration](OMARCHY.md) | +| Use the Windows tray and recovery tools | [Windows guide](WINDOWS.md) | +| Install from the signed Debian/Ubuntu repository | [APT setup](APT_REPOSITORY.md) | + +## Understand and contribute + +| Topic | Read | +|---|---| +| Local setup, tests and pull requests | [Contributing](../CONTRIBUTING.md) | +| Components, input and audio flow | [Architecture](ARCHITECTURE.md) | +| Recorded measurements and how to reproduce them | [Benchmarks](BENCHMARKS.md) | +| Site changes, media and icon exports | [Website and artwork](WEBSITE.md) | +| The character behind the app | [Meet Klicky](CHARACTER.md) | +| Input permissions, network behavior and vulnerability reports | [Security](../SECURITY.md) | +| Community expectations and private reports | [Code of Conduct](../CODE_OF_CONDUCT.md) | +| Project origins and third-party assets | [Acknowledgements](../ACKNOWLEDGEMENTS.md) | + +## Build and distribute packages + +These guides are for contributors working on distribution and release tooling. + +- [Packaging and release checklist](PACKAGING.md) +- [Signed APT repository maintenance](MAINTAINING_APT.md) +- [Microsoft Store packaging](WINDOWS_STORE.md) + +For a question that the guides do not answer, use [Discussions Q&A](https://github.com/Muneer320/klicky/discussions/categories/q-a). For a reproducible problem, [open a bug report](https://github.com/Muneer320/klicky/issues/new/choose). diff --git a/docs/RELEASE_READINESS.md b/docs/RELEASE_READINESS.md deleted file mode 100644 index 4bbff8c..0000000 --- a/docs/RELEASE_READINESS.md +++ /dev/null @@ -1,59 +0,0 @@ -# Release checklist - -Klicky v0.6.1 fixes Linux removal of native and legacy Omarchy controls, prevents duplicate legacy/native bar controls, and consolidates installation and distribution guidance. Supported platforms and audio backends are unchanged: Linux, macOS and Windows 11 x64. Linux ships Debian/Arch packages; Windows offers Microsoft Store distribution plus an unsigned per-user installer and portable ZIP; macOS uses the versioned source installer, with its menu helper included by default. - -For each release, keep the preparation PR open until approval to transition the public installation commands and website. A candidate build is not a published release. The older Windows preview remains a historical download; new Windows users should use the stable installer. - -## Build a candidate without publishing - -The [release workflow](../.github/workflows/release.yml) accepts a manual run on a reviewed branch or a `v*` tag. Tag runs verify the Cargo version. It has read-only repository permissions and **does not publish**, mark a release latest or deploy APT. - -```bash -gh workflow run release.yml --ref YOUR_REVIEWED_BRANCH -gh run list --workflow release.yml -gh run download RUN_ID --name klicky-0.6.1-release-candidate --dir candidate -``` - -The workflow reuses Linux/macOS CI, macOS Intel/Apple Silicon installation/removal, Windows core checks, Debian/Arch packaging and signed APT integration checks. It builds the Windows packages using the pinned toolchain and Inno compiler, archives the exact source, then verifies the combined asset set. `RELEASE-MANIFEST.json` records source revision/tree, signing status, sizes and hashes; `SHA256SUMS` also covers the manifest. - -A separate Windows 11 runner removes its inherited scan exclusions, updates Defender signatures and scans the original Windows packages plus the expanded portable payload. Release assembly requires that scan to pass. `windows-security-evidence` records the engine/signature versions and scanned file hashes; unavailable protection, remaining exclusions, stale signatures or detections fail the check. These changes strengthen protection only on the disposable runner and never change a user's PC. This is an antivirus scan of those files, not code signing or a guarantee against future detections. The ARM runner only scans the x64 files as data and does not qualify ARM application support. - -Expected payloads: - -- `klicky_0.6.1-1_amd64.deb` -- `klicky-0.6.1-1-x86_64.pkg.tar.zst` -- `klicky-0.6.1-windows-x64-setup.exe` and its `.sha256` -- `klicky-0.6.1-windows-x64.zip` and its `.sha256` -- `klicky-0.6.1-source.tar.gz` - -## Before approval - -1. Use focused issues/PRs and dedicated branches. Complete independent review and resolve valid findings. Verify the candidate source matches the intended merged tree. -2. Synchronize Cargo/lockfile, Debian/Arch/resource versions, changelog, installer selection, README, guides and website. Check the source archive retains executable script modes. -3. Pass all candidate jobs. Verify bundled sounds, dependency notices/source obligations, payload hashes and exact source identity. Exclude personal configuration, recordings, credentials and local fixtures. -4. Exercise Windows first install, running/paused update, startup, configuration/custom-pack preservation, normal removal and `-Purge` with disposable data. Verify the missing-CLI recovery path, modified/foreign-file refusal and active-bundle interlock. Keep a recoverable backup when testing a daily installation. -5. Exercise Linux package/source lifecycle and native macOS setup/removal. Containers and hosted runners cover packaging and control behavior; they do not provide physical keyboards or audible output. -6. Scan the exact Windows files with current antivirus protection enabled. A prior Microsoft determination applies to the submitted file, not all later builds. Keep signatures, hashes and results with the candidate evidence. -7. Check user-facing sound timing and recovery on the available desktop/output routes. Retain measured results separately from listening feedback. Record unavailable physical-latency/baseline and additional-hardware checks as deferred, never as passed. Review their release impact explicitly. -8. Obtain explicit approval for the concrete version, assets, unsigned Windows status and any deferred validation. A merge, green CI or candidate artifact does not authorize publication. - -## Approved publication - -Only after approval, merge the preparation PR, create the version tag on the approved source and run the candidate workflow for that tag. Verify/download the resulting final assets and repeat exact-byte security/hash checks. Do not overwrite published assets with a rebuild. - -The Pages/APT workflow holds the current site when a source-version bump is merged before its matching stable release exists. Publication of the matching release allows the new installation commands and site to deploy together; a manual run with a mismatched source version is refused. - -Create the GitHub release with the approved notes, attach the five payloads, Windows sidecars, manifest and `SHA256SUMS`, mark it non-prerelease and latest, then verify public downloads. Windows code signing is separate from versioning; describe the unsigned installer plainly. - -Publish the signed APT archive using the [maintenance procedure](MAINTAINING_APT.md#publication), retaining every authenticated existing package version. Dispatch its workflow on `master`: the current Pages environment rejects deployments from version tags, even when their release-event build succeeds. A release created with GitHub's workflow token does not automatically trigger another workflow. Confirm the archive and Pages deployment completed before announcing the updated one-line commands. - -## After publication - -- Verify public asset names/sizes/hashes and stable/latest state. Run the downloaded Windows installer, not just a local build with similar source. -- Check website install/removal endpoints, README/download links, source checksums, sound previews and custom domain. Verify APT signatures, candidate version and retained historical packages. -- Record exact release evidence in the PR or private continuity notes. Preserve unresolved recovery material and remove merged branches when no longer needed. -- Additional package-manager submissions are separate reviewed publications. Do not advertise a command until that channel is actually available. - -## Microsoft Store updates - -Keep the [Store identity and package-version mapping](WINDOWS_STORE.md#build) stable across updates. Build and validate the exact MSIX, submit it with accurate listing/capability information and review Microsoft's determination. Certification and public publication are separate steps; use a manual publication hold until the release is approved. Verify the public listing and production package after publishing, then synchronize installation links and documentation. Store signing applies to the delivered MSIX, not the standalone EXE/ZIP assets. diff --git a/docs/WEBSITE.md b/docs/WEBSITE.md index 3e911de..a954b49 100644 --- a/docs/WEBSITE.md +++ b/docs/WEBSITE.md @@ -20,7 +20,20 @@ There is no frontend framework, remote font service, account, analytics or globa Keep the archive template markers `PUBLIC_URL`, `LATEST_VERSION`, `VERSIONS` and `FINGERPRINT`. The builder escapes dynamic metadata. Preserve relative links to `klicky.sources`, both signing-key formats and `dists/stable/InRelease`; the site must work at `/` and `/klicky/`. -`copy_site_assets` publishes the curated website/branding folders, field guide, privacy policy and four install/remove scripts. The preferred social image is `/assets/social-preview.jpg`; `/assets/social-preview.png` remains compatible with older links. Both are 1280 × 640 and under 1 MB. Never copy reference boards, internal character briefs, planning files, local test output or unrelated directories into public assets. +`copy_site_assets` publishes the curated website/branding folders, field guide, privacy policy and four install/remove scripts. The preferred social image is `/assets/social-preview.jpg`; `/assets/social-preview.png` remains compatible with older links. Both are 1280 × 640 and under 1 MB. The builder publishes only the curated asset directories. + +## Artwork + +The [asset library](../assets/branding) contains the shared SVG/PNG marks, mascot illustrations, wordmarks and social poster. [Meet Klicky](CHARACTER.md) describes the character. Optimized site images live in `assets/website/mascot`; native application icons are committed under `assets/branding` and `packaging/windows`. + +To regenerate PNG/ICO and macOS template icons after changing their SVG sources: + +```sh +npm ci --prefix tools/branding --ignore-scripts +npm run --prefix tools/branding build +``` + +The pinned resvg exporter uses the colour mark for PNG/ICO and the monochrome mark for macOS templates. The branding workflow checks generated files against Git. Normal Cargo builds use the committed icons and do not require Node. Keep font and demo attributions with their assets; see [acknowledgements](../ACKNOWLEDGEMENTS.md). ## Preview and validate @@ -55,16 +68,14 @@ Use `--ffmpeg /path/to/ffmpeg` if needed. Examples are offline sample sequences ## Publication -The reviewed Pages/APT workflow rebuilds the complete signed archive, verifies retained package history and keeps CNAME. Do not deploy the landing HTML alone or replace this with a generic static-site workflow. See [APT maintenance](MAINTAINING_APT.md). +The Pages/APT workflow rebuilds the complete signed archive, verifies retained package history and keeps CNAME. Do not deploy the landing HTML alone or replace this with a generic static-site workflow. See [APT maintenance](MAINTAINING_APT.md). The custom-domain CNAME points to `muneer320.github.io`; GitHub Pages must retain the same domain and HTTPS setting. Installation endpoints are `/install.sh` and `/install.ps1`; removal uses `/uninstall.sh` and `/uninstall.ps1`. Publishing website changes does not publish application releases or update installed icons. Keep version/download wording aligned with real release assets. The APT release-event path skips prereleases, and candidate builds do not publish a release. -## Search and AI-search follow-up - -The site serves its product facts and installation text in HTML, with canonical URLs, a sitemap, crawlable links and SoftwareApplication/Person identity. Keep visible descriptions, desktop-control instructions and structured data consistent. Do not add ratings, performance figures or package-manager availability that the project cannot substantiate. +## Search metadata -After meaningful page changes, check the verified domain in Google Search Console and Bing Webmaster Tools: sitemap processing, URL inspection, crawl/indexing problems and query/page performance. Bing’s AI Performance report can show citations and grounding queries when data is available. A public `site:` search is only a spot check, not an indexing or ranking report. +The pages contain canonical URLs, a sitemap, crawlable links and SoftwareApplication/Person structured data. Keep these consistent with visible product and installation information. Use the shared social poster and relative asset paths so links work on both the custom domain and GitHub Pages. -Google’s [AI search guidance](https://developers.google.com/search/docs/appearance/ai-features) uses the same crawlability and helpful-content foundations as ordinary search; there is no special AI schema required. Prioritize accurate answers and working links over extra crawler-specific files. Webmaster dashboards require the maintainer’s signed-in account; never treat an inaccessible report as a passed check. +Google's [search and AI-feature guidance](https://developers.google.com/search/docs/appearance/ai-features) covers crawlability and helpful content; no special AI schema is required. Keep ratings, performance figures and package-manager availability grounded in the released product. diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md index bed240d..1717a7a 100644 --- a/docs/WINDOWS.md +++ b/docs/WINDOWS.md @@ -114,7 +114,7 @@ $env:KLICKY_SYSTEM_SOUNDS_DIR = (Resolve-Path .\sounds).Path .\target\release\klicky-desktop.exe --paused ``` -The console entry point `klicky.exe start` uses the same engine. `--seconds 30` bounds a session; `--benchmark` prints aggregate internal dispatch diagnostics at exit, without key names. The shared [brand assets](https://github.com/Muneer320/klicky/blob/master/docs/BRANDING.md) are committed; Node is not needed to build or run the app. +The console entry point `klicky.exe start` uses the same engine. `--seconds 30` bounds a session; `--benchmark` prints aggregate internal dispatch diagnostics at exit, without key names. The shared [brand assets](https://github.com/Muneer320/klicky/tree/master/assets/branding) are committed; Node is not needed to build or run the app. @@ -132,6 +132,6 @@ The installer compiler is official Inno Setup 7.1.1 x64. Output is under `target For unattended installation, use `/VERYSILENT /SUPPRESSMSGBOXES /NORESTART` and an explicit `/LOG="C:\path\to\install.log"`. Fresh silent installs do not launch the app. `/TASKS="startup"` opts in to login startup; custom `/DIR` locations are refused. Exit 10 means files installed but startup registration or restarting was not confirmed; inspect the log and tray. -[Release engineering checklist](https://github.com/Muneer320/klicky/blob/master/docs/RELEASE_READINESS.md) · [Measurement tooling](https://github.com/Muneer320/klicky/blob/master/tools/windows-qualification/USAGE.md) · [Microsoft Store packaging](https://github.com/Muneer320/klicky/blob/master/docs/WINDOWS_STORE.md) +[Release engineering checklist](https://github.com/Muneer320/klicky/blob/master/docs/PACKAGING.md#release-checklist) · [Measurement tooling](https://github.com/Muneer320/klicky/blob/master/tools/windows-qualification/USAGE.md) · [Microsoft Store packaging](https://github.com/Muneer320/klicky/blob/master/docs/WINDOWS_STORE.md) diff --git a/docs/WINDOWS_STORE.md b/docs/WINDOWS_STORE.md index 68065bd..d08c6ef 100644 --- a/docs/WINDOWS_STORE.md +++ b/docs/WINDOWS_STORE.md @@ -95,7 +95,7 @@ for login startup when both EXE and Store installations are present. 6. Repeat existing Windows core/package checks and Linux/macOS CI checks. Keep credentials, certificates, test recordings and account-specific submission -notes outside the repository. Store publication remains a separate approval step. +notes outside the repository. Certification and public Store publication are separate steps. ## Store submission diff --git a/packaging/apt/guide.html b/packaging/apt/guide.html index dedd939..e157dcb 100644 --- a/packaging/apt/guide.html +++ b/packaging/apt/guide.html @@ -1024,13 +1024,13 @@