docs: add user-facing README and contributor guide

CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to OpenInCode
+
+## Development requirements
+
+- macOS 12 or newer
+- Swift 6.2 or newer
+- Xcode 26 or newer for the `actool` step that compiles the current Icon Composer asset
+- Visual Studio Code or Visual Studio Code Insiders for end-to-end testing
+
+OpenInCode uses Swift Package Manager and Apple frameworks only; there are no external package dependencies.
+
+## Build and test
+
+Clone the repository, then build the SwiftPM executable and run the focused tests:
+
+```sh
+swift build
+./scripts/test.sh
+```
+
+`./scripts/test.sh` is the canonical test command. It runs the Swift tests with warnings treated as errors and validates the generated Homebrew cask.
+
+## Build the app bundle
+
+Assemble an unsigned Release app for verification:
+
+```sh
+OPEN_IN_CODE_SIGNING=unsigned ./scripts/build-app.sh release
+```
+
+The app is written to `.build/app/Open in Code.app`.
+
+The packaging script applies an ad-hoc signature by default so Finder automation entitlements are available during local development. Set `OPEN_IN_CODE_SIGNING=unsigned` to skip signing. Set `ARCHES="arm64 x86_64"` when a universal app is required.
+
+To try the local build:
+
+1. Copy `.build/app/Open in Code.app` to `/Applications`.
+2. Hold Command and drag the app from `/Applications` to a Finder toolbar.
+3. Click the toolbar icon while viewing a folder or selecting a file.
+
+## Publishing a release
+
+Pushing a `v*` tag runs `.github/workflows/release.yml`. The workflow builds a universal app, signs it, creates a GitHub release, and updates `Casks/open-in-code.rb` in [`sozercan/homebrew-repo`](https://github.com/sozercan/homebrew-repo).
+
+Public releases require all of these GitHub Actions secrets:
+
+- `HOMEBREW_REPO_SSH_KEY`: the private half of a write-enabled deploy key for `sozercan/homebrew-repo`
+- `MACOS_CERTIFICATE`, `MACOS_CERTIFICATE_PWD`, `MACOS_KEYCHAIN_PWD`: a Developer ID Application PKCS#12 and its temporary keychain credentials
+- `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`: notarization credentials
+
+Tag pushes and manual runs with `publish=true` fail unless Developer ID signing and notarization succeed. A manual run with `publish=false` may use ad-hoc signing for validation, but it never creates a GitHub release or updates Homebrew. Prerelease tags create GitHub prereleases but do not replace the stable Homebrew cask.
+
+Do not create tags, publish releases, notarize artifacts, update the Homebrew tap, or change signing identities, team IDs, bundle identifiers, or release secrets as part of a normal contribution.

README.md

@@ -1,66 +1,91 @@
-# OpenInCode
+<p align="center">
+  <img src="docs/assets/open-in-code-icon.png" width="112" alt="Open in Code app icon">
+</p>
 
-Finder toolbar app that opens the current Finder folder—or the folder containing the selected file—in Visual Studio Code.
+<h1 align="center">Open in Code</h1>
 
-OpenInCode prefers stable Visual Studio Code and falls back to Visual Studio Code Insiders when stable is not installed.
+<p align="center">
+  Open the folder you are viewing in Finder—or the folder containing a selected item—in Visual Studio Code with one click.
+</p>
+
+<p align="center">
+  <a href="https://github.com/sozercan/OpenInCode/releases/latest"><img src="https://img.shields.io/github/v/release/sozercan/OpenInCode?style=flat-square&amp;label=release&amp;color=0A84FF" alt="Latest release"></a>
+  <img src="https://img.shields.io/badge/macOS-12%2B-1f2937?style=flat-square&amp;logo=apple&amp;logoColor=white" alt="macOS 12 or newer">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-34c759?style=flat-square" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#add-it-to-finder">Set up</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="CONTRIBUTING.md">Contribute</a>
+</p>
+
+<p align="center">
+  <img src="docs/assets/open-in-code-hero.png" width="100%" alt="Open in Code takes a selected Finder item and opens its folder in Visual Studio Code">
+</p>
+
+Open in Code is a small, native macOS utility built for the Finder toolbar. It gets you from the file you are looking at to the matching VS Code workspace without opening a terminal or navigating to the folder again.
+
+| **One click** | **Finder-aware** | **Stable or Insiders** |
+| --- | --- | --- |
+| Lives in the Finder toolbar, ready whenever you need it. | Uses your selection when available and the current Finder window when it is not. | Prefers Visual Studio Code and falls back to Visual Studio Code Insiders. |
 
 ## Requirements
 
 - macOS 12 or newer
 - Visual Studio Code or Visual Studio Code Insiders
-- Swift 6.2 or newer
-- Xcode 26 or newer for the `actool` step that compiles the current Icon Composer asset
 
 ## Install
 
-Install the latest release from the Homebrew tap:
+### Homebrew
 
 ```sh
 brew install --cask sozercan/repo/open-in-code
 ```
 
-Release archives are also available from the [GitHub Releases](https://github.com/sozercan/OpenInCode/releases) page.
+### Direct download
 
-To build from source:
+Download the app from [GitHub Releases](https://github.com/sozercan/OpenInCode/releases), then move **Open in Code.app** to `/Applications`.
 
-1. Clone this repository.
-2. Run `./scripts/build-app.sh release`. The script uses SwiftPM and creates `.build/app/Open in Code.app`.
-3. Copy `Open in Code.app` to `/Applications`.
-4. Hold Command and drag the app from `/Applications` to a Finder toolbar.
-5. Click the toolbar icon while viewing a folder or selecting a file.
+## Add it to Finder
 
-The first use asks for permission to control Finder. If permission was denied, enable **Open in Code → Finder** here:
+1. Open `/Applications` in Finder.
+2. Hold <kbd>⌘ Command</kbd> and drag **Open in Code** to the Finder toolbar.
+3. Drop it wherever you want the button to live.
 
-- macOS 13 or newer: **System Settings → Privacy & Security → Automation**
-- macOS 12: **System Preferences → Security & Privacy → Privacy → Automation**
+Hold <kbd>⌘ Command</kbd> while dragging the button again to reposition or remove it.
 
-The local packaging script applies an ad-hoc signature by default so Finder automation entitlements are available during development. Public release artifacts should be signed with a Developer ID Application certificate and notarized before distribution.
+## How it works
 
-## Development
+Open a Finder window, optionally select an item, and click **Open in Code**.
 
-Build the SwiftPM executable and run the focused path and editor-selection tests:
+| Finder state | What opens in VS Code |
+| --- | --- |
+| A folder is selected | The selected folder |
+| A file or Finder package is selected | Its containing folder |
+| Multiple items are selected | The first selected item's folder |
+| Nothing is selected | The folder shown in the front Finder window |
 
-```sh
-swift build
-./scripts/test.sh
-```
+## Finder permission
 
-Assemble an unsigned Release app bundle for verification:
+> [!NOTE]
+> On first use, macOS asks whether **Open in Code** may control Finder. Allow access so the app can read the current Finder selection.
 
-```sh
-OPEN_IN_CODE_SIGNING=unsigned ./scripts/build-app.sh release
-```
+<details>
+<summary><strong>If Finder access was previously denied</strong></summary>
+
+Enable **Open in Code → Finder** in the appropriate settings pane:
 
-Set `ARCHES="arm64 x86_64"` when a universal app is required.
+- **macOS 13 or newer:** System Settings → Privacy & Security → Automation
+- **macOS 12:** System Preferences → Security & Privacy → Privacy → Automation
 
-## Publishing a release
+</details>
 
-Pushing a `v*` tag runs `.github/workflows/release.yml`. The workflow builds a universal app, signs it, creates a GitHub release, and updates `Casks/open-in-code.rb` in [`sozercan/homebrew-repo`](https://github.com/sozercan/homebrew-repo).
+## Contributing
 
-Public releases require all of these Actions secrets:
+Source builds, tests, packaging, and release instructions live in [CONTRIBUTING.md](CONTRIBUTING.md).
 
-- `HOMEBREW_REPO_SSH_KEY`: the private half of a write-enabled deploy key for `sozercan/homebrew-repo`
-- `MACOS_CERTIFICATE`, `MACOS_CERTIFICATE_PWD`, `MACOS_KEYCHAIN_PWD`: a Developer ID Application PKCS#12 and its temporary keychain credentials
-- `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`: notarization credentials
+---
 
-Tag pushes and manual runs with `publish=true` fail unless Developer ID signing and notarization succeed. A manual run with `publish=false` may use ad-hoc signing for validation, but it never creates a GitHub release or updates Homebrew. Prerelease tags create GitHub prereleases but do not replace the stable Homebrew cask.
+<p align="center"><sub>Made for macOS · Licensed under the <a href="LICENSE">MIT License</a></sub></p>