Skip to content

armgit / cra

Public Imported from GitHub
0

The open-source Arc replacement for macOS. Spaces, pinned tabs, split view, Little Windows and Arc's shortcuts on Chromium, with your Arc sidebar imported in one go.

README for a bigger audience, contributing guide, security policy, issue forms

Victoref345193e325
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..e9edace
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,52 @@
+name: Bug report
+description: Something in Cra doesn't work, or works differently from Arc.
+labels: [bug]
+body:
+ - type: textarea
+ id: what
+ attributes:
+ label: What happened
+ description: What you did, what you expected, and what Cra did instead. A screenshot or screen recording helps a lot.
+ validations:
+ required: true
+ - type: textarea
+ id: steps
+ attributes:
+ label: Steps to repeat it
+ placeholder: |
+ 1. Open a new tab with ⌘T
+ 2. …
+ validations:
+ required: true
+ - type: input
+ id: version
+ attributes:
+ label: Cra version
+ description: Cra ▸ About Cra, or the first line of the Help menu.
+ placeholder: 0.1.14 (Chromium 156.0.8078.48)
+ validations:
+ required: true
+ - type: input
+ id: macos
+ attributes:
+ label: macOS version
+ placeholder: macOS 26.1
+ validations:
+ required: true
+ - type: dropdown
+ id: from
+ attributes:
+ label: Imported from
+ description: Which browser you brought your data over from, if any.
+ options:
+ - Nothing
+ - Arc
+ - Dia
+ - Chrome, Brave, Edge or another Chromium browser
+ - Firefox or Zen
+ - Safari
+ - type: textarea
+ id: extra
+ attributes:
+ label: Anything else
+ description: Extensions involved, a managed (MDM) Mac, or lines from ~/Library/Application Support/Cra/chromium.log.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..595d6af
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+ - name: Question or idea
+ url: https://github.com/VictorKildahl/cra/discussions
+ about: Ask how something works or talk through an idea in Discussions.
+ - name: Security problem
+ url: https://github.com/VictorKildahl/cra/security/advisories/new
+ about: Report vulnerabilities privately, not as a public issue.
+ - name: Help centre
+ url: https://crabrowser.app/help
+ about: Guides to every part of Cra.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..de385c5
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,20 @@
+name: Feature request
+description: Something Arc did that Cra doesn't yet, or an idea of your own.
+labels: [enhancement]
+body:
+ - type: textarea
+ id: what
+ attributes:
+ label: What you'd like
+ description: What it should do, and what you'd use it for.
+ validations:
+ required: true
+ - type: textarea
+ id: arc
+ attributes:
+ label: How Arc did it
+ description: If this is an Arc feature, how it looked and behaved there. Screenshots or a recording from Arc are gold.
+ - type: markdown
+ attributes:
+ value: |
+ Cra has no built-in AI, account or telemetry, so requests in those directions will be closed. The [roadmap](https://crabrowser.app/roadmap) lists what's already planned.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..076007b
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,7 @@
+## What and why
+
+<!-- What this changes and why. Link the issue: Fixes #123 -->
+
+## How I tested it
+
+<!-- What you ran and clicked. For anything visible, add a screenshot or a short clip, and for an Arc feature, Arc next to Cra. -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..9dea58f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,56 @@
+# Contributing to Cra
+
+Thanks for helping. Bug reports with steps to repeat them are the most useful thing
+you can send. Code is welcome too, within the few rules below.
+
+## What fits
+
+- **Arc parity, one to one.** Where Arc had a feature, Cra matches it: the same layout,
+ shortcuts, animations and hover states. When you change one, compare it with Arc and
+ include a screenshot or clip of both.
+- **No built-in AI.** Arc Max-style features (tidy tabs, summaries, LLM search) are out
+ of scope.
+- **No account, no server, no telemetry.** Everything stays on the user's Mac.
+- **Native first.** The app is AppKit and SwiftUI; web content is Chromium through CEF.
+
+For anything bigger than a bug fix, open an issue or a
+[discussion](https://github.com/VictorKildahl/cra/discussions) first, so we can agree on
+the shape before you spend the time.
+
+## Getting set up
+
+ git clone https://github.com/VictorKildahl/cra.git
+ cd cra
+ scripts/build.sh # first run fetches CEF
+ scripts/dev.sh # debug CraDev.app, rebuilds + relaunches on save
+
+You need macOS 14+ on Apple silicon, Xcode 16+ and CMake (`brew install cmake`).
+[docs/development.md](docs/development.md) has the code layout, the `cra://` scripting
+hooks and how to run a test instance next to your daily Cra.
+
+## Sending a change
+
+1. Fork, branch from `main`, keep the change to one thing.
+2. Match the code around you: naming, comments and structure. Doc comments say *why*,
+ not what.
+3. Run it. CI only checks that Cra builds and signs, so say in the PR how you tested
+ it, and add a screenshot or a short clip for anything visible.
+4. Don't touch the release pipeline, signing or the CEF pin unless that's the point of
+ the PR. Releases are cut by the maintainer.
+
+## Chromium and CEF
+
+The CEF version is pinned in `scripts/fetch-cef.sh`, which downloads Cra's own CEF build
+(H.264/AAC and the patches in `scripts/cef-patches`) from this repository's releases, so
+you never need to build Chromium yourself. If your fix needs a new CEF patch, say so in
+the issue first: the maintainer rebuilds CEF for it, and every patch has to be carried
+through each Chromium update.
+
+## Security
+
+Please don't open public issues for vulnerabilities. See [SECURITY.md](SECURITY.md).
+
+## Licence
+
+By contributing you agree that your contribution is licensed under the
+[MIT licence](LICENSE).
diff --git a/README.md b/README.md
index ac9e2d1..2c061dd 100644
--- a/README.md
+++ b/README.md
@@ -2,140 +2,157 @@
<img src="brand/cra-segments-icon.svg" alt="Cra logo" width="128" height="128">
</p>
-# Cra
+<h1 align="center">Cra</h1>
-A native macOS browser built on Chromium (CEF), shaped after the parts of Arc
-worth keeping: a sidebar instead of a tab strip, spaces, pinned tabs with a
-home URL, favorites shared across spaces, a command bar for new tabs that
-searches open and archived tabs, auto-archiving, folders, and Chrome DevTools.
-
-Shell: Swift (AppKit + SwiftUI). Engine: Chromium Embedded Framework.
-
-## Install
-
-Needs macOS 14 or later on Apple silicon.
-
-**[Download Cra.dmg](https://github.com/VictorKildahl/cra/releases/latest/download/Cra.dmg)**,
-open it and drag Cra to Applications. Cra is signed and notarized by Apple, so it opens
-like any other app, and from then on it keeps itself up to date (Cra ▸ Check for Updates…).
-
-**Prefer Terminal?** This puts the latest Cra in your Applications folder and opens it:
-
- curl -fsSL https://raw.githubusercontent.com/VictorKildahl/cra/main/scripts/install.sh | bash
-
-## Support Cra
-
-Cra is free, open source and has no investors or ads. If it earns a place on your Mac,
-[sponsor it on GitHub](https://github.com/sponsors/VictorKildahl): it pays for the Chromium
-updates, the Apple signing and the time it takes to keep a browser going. Sponsoring unlocks
-nothing in the app; every feature stays free for everyone.
-[Where the money goes](https://crabrowser.app/support).
-
-## Build
-
- scripts/build.sh # fetches CEF on first run, builds build/Cra.app
- scripts/run.sh # build if needed, then open
- scripts/dev.sh # dev loop: debug CraDev.app, rebuilds + relaunches on save (~4 s)
-
-Requirements: Xcode 16+, CMake (`brew install cmake`).
-
-## Release
-
-`scripts/release.sh` builds, signs with a Developer ID, notarizes, and packages a DMG and
-zip into `build/dist`. Pushing a `v*` tag runs the same through GitHub Actions and
-publishes a release. See `docs/release.md` for the one-time certificate setup.
+<p align="center">
+ A native macOS browser with a sidebar instead of a tab strip.<br>
+ Free and open-source, built to replace Arc one to one.
+</p>
-## Layout
+<p align="center">
+ <a href="https://github.com/VictorKildahl/cra/releases/latest/download/Cra.dmg"><b>Download for macOS</b></a> ·
+ <a href="https://crabrowser.app">crabrowser.app</a> ·
+ <a href="https://crabrowser.app/release-notes">What's new</a> ·
+ <a href="https://crabrowser.app/help">Help</a>
+</p>
-- `Sources/Cra` — the app (model, store, sidebar, command bar, windows)
-- `Sources/CraCEF` — Objective-C++ bridge to CEF
-- `Sources/CraHelper` — Chromium subprocess executable
-- `docs/arc-reverse-engineering.md` — what was learned from Arc and how
-- `vendor/cef` — CEF binary distribution (not committed)
+<p align="center">
+ <a href="https://github.com/VictorKildahl/cra/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/VictorKildahl/cra?label=release"></a>
+ <img alt="macOS 14+, Apple silicon" src="https://img.shields.io/badge/macOS-14%2B%20·%20Apple%20silicon-lightgrey">
+ <a href="LICENSE"><img alt="MIT licence" src="https://img.shields.io/github/license/VictorKildahl/cra"></a>
+</p>
-Data lives in `~/Library/Application Support/Cra`.
+<p align="center">
+ <img src="docs/screenshots/cra.jpg" alt="Cra with favorites, a space with pinned tabs and folders, and a split view in the sidebar" width="760">
+</p>
-## Scripting hooks
+Arc ends on 22 December 2026. Cra keeps the parts of it worth keeping: spaces, pinned tabs
+that remember where they started, favorites, a command bar that searches everything,
+Today tabs that archive themselves, split view, Little Windows and Arc's keyboard
+shortcuts. Import your Arc sidebar in one go and carry on where you left off.
-Cra registers the `cra://` scheme so it can be driven from a shell (handy for
-testing without touching the keyboard):
+The app is Swift (AppKit and SwiftUI) and the engine is Chromium, through the Chromium
+Embedded Framework, so sites and Chrome extensions work as they do in Chrome.
- open "cra://action/newTab" # any action id from KeyBindings.swift
- open "cra://commandbar?query=github" # open the command bar with text
- open "cra://open?url=https://example.com&background=1"
- open "cra://dismiss" # close sheets, command bar, find bar
+## Install
-Links from other apps and browsers only reach `commandbar`, `dismiss` and `open` with an
-http(s) URL; pages inside Cra reach none of them. The rest (`action`, `navigate`, `key`,
-`import`, `debug`) run scripts and DevTools Protocol commands, so they need either
-`defaults write dk.kildahl.cra scriptingURLs -bool YES` or a test instance's
-`CRA_COMMAND_FILE`.
+<p align="center">
+ <a href="https://github.com/VictorKildahl/cra/releases/latest/download/Cra.dmg"><img alt="Download for Mac" src="docs/assets/download.png" width="272" height="60"></a>
+</p>
-## Little Windows (Arc's Little Arc)
+<p align="center">
+ Open the DMG and drag Cra to Applications.<br>
+ It's signed and notarized by Apple, and keeps itself up to date. Needs Apple silicon.
+</p>
-Links from other apps open in a Little Window: a small, sidebar-less window with one
-search pill and an "Open in <Space> ⌘O" button. The page is not in the sidebar; closing
-the window (⌘W) archives it to the Library, ⌘O (or the chevron menu) moves it into a space
-as a Today tab, keeping the live page. ⌥⌘N opens an empty one. Settings → Tabs turns the
-link routing off; `open "cra://open?url=…&little=1"` opens one from a shell.
+## Coming from Arc
+
+| Arc feature | Cra |
+|---|:---:|
+| Spaces | ✅ |
+| Pinned tabs | ✅ |
+| Today tabs and auto-archive | ✅ |
+| Favorites | ✅ |
+| Folders | ✅ |
+| Command bar | ✅ |
+| Little Arc | ✅ |
+| Split View | ✅ |
+| Picture in Picture | ✅ |
+| Developer Mode | ✅ |
+| Library | ✅ |
+| Air Traffic Control | ✅ |
+| Live folders | ✅ |
+| Profiles | ✅ |
+| Private windows | ✅ |
+| Arc's keyboard shortcuts | ✅ |
+| Import from Arc | ✅ |
+| Easels | Not yet |
+| Boosts | Not yet |
+| Peek | Not yet |
+| Notes | Not yet |
+| Arc Max | No, Cra has no built-in AI |
+
+The [roadmap](https://crabrowser.app/roadmap) lists what's next.
## Import
-Cra menu → Import from Arc or Dia…, or Settings → Import. Imports from Arc, Dia,
-Chrome, Brave, Edge, Opera, Opera GX, Vivaldi, Chromium, Firefox, Zen and Safari: Arc's
-StorableSidebar.json / StorableArchiveItems.json, Dia's profile containers, and
-bookmarks, history, extensions, passwords and cookies from the other browsers.
-Spaces with the same name merge; tabs already present are skipped.
-Headless: `open "cra://import?source=arc&archive=1&settings=1"`.
-
-## Keyboard
+On first launch, or later from Cra ▸ Import from Arc or Dia…, Cra brings over:
-Arc's defaults: ⌘T new tab · ⌘L command bar / edit URL · ⌘W close tab (window
-when no tab) · ⇧⌘W close window · ⇧⌘T restore closed tab · ⌘S sidebar ·
-⇧⌘D toolbar · ⌘D pin/unpin · ⇧⌘C copy URL · ⇧⌥⌘C copy as Markdown ·
-⌘1…9 go to tab · ⌃1…9 go to space · ⌥⌘←/→ spaces · ⌥⌘↑/↓ tabs · ⌃Tab recent
-tab · ⇧⌘K clear Today · ⌘[ / ⌘] back/forward · ⌘Y history · ⇧⌘L library ·
-⇧⌘J downloads · ⌥⌘I DevTools · ⌥⌘J console · ⌥⌘U source · ⌘F find.
-Like Chrome, pages get first chance at unreserved shortcuts (⌘F in Docs works).
-Every shortcut can be changed in Settings → Shortcuts; overrides are saved to
-`~/Library/Application Support/Cra/keybindings.json`.
+- **Arc:** spaces, pinned tabs, folders, favorites and the archive, plus passwords and
+ sign-ins.
+- **Dia, Chrome, Brave, Edge, Opera, Vivaldi, Chromium:** tabs, bookmarks, history,
+ passwords, sign-ins and extensions.
+- **Zen and Firefox:** open tabs, bookmarks and history, and Zen's spaces, Essentials and
+ pinned tabs.
+- **Safari:** whatever Safari exports itself (File ▸ Export Browsing Data): bookmarks,
+ history and passwords.
-## Rendering calibration hook
+Spaces with the same name merge, tabs that are already there are skipped, and every
+step can be skipped.
-`open "cra://debug?lift=0&liftInactive=0.75&alpha=1&material=13&state=follows&appearance=dark"`
-changes the vibrancy parameters live (see `Sources/Cra/UI/Tuning.swift`). `material` is the
-raw `NSVisualEffectView.Material` value, `alpha` scales the gradient opacity.
+## Keyboard
-## DevTools
+Cra uses Arc's defaults, and every one can be changed in Settings ▸ Shortcuts. The ones
+you'll use most:
+
+| Shortcut | Action |
+|---|---|
+| <kbd>⌘</kbd> <kbd>T</kbd> | New tab (command bar) |
+| <kbd>⌘</kbd> <kbd>L</kbd> | Edit the URL |
+| <kbd>⌘</kbd> <kbd>W</kbd> | Close tab |
+| <kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>T</kbd> | Restore closed tab |
+| <kbd>⌘</kbd> <kbd>D</kbd> | Pin or unpin tab |
+| <kbd>⌘</kbd> <kbd>S</kbd> | Show or hide the sidebar |
+| <kbd>⌃</kbd> <kbd>1</kbd>…<kbd>9</kbd> | Go to space |
+| <kbd>⌘</kbd> <kbd>1</kbd>…<kbd>9</kbd> | Go to tab |
+| <kbd>⌃</kbd> <kbd>Tab</kbd> | Switch to recent tab |
+| <kbd>⌃</kbd> <kbd>⇧</kbd> <kbd>=</kbd> | Split view |
+| <kbd>⌥</kbd> <kbd>⌘</kbd> <kbd>N</kbd> | New Little Window |
+| <kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>N</kbd> | New incognito window |
+| <kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>C</kbd> | Copy URL |
+| <kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>K</kbd> | Clear Today |
+| <kbd>⌘</kbd> <kbd>Y</kbd> | History and archive |
+| <kbd>⌃</kbd> <kbd>D</kbd> | Developer Mode |
+| <kbd>⌥</kbd> <kbd>⌘</kbd> <kbd>I</kbd> | DevTools |
+
+Pages get the first chance at shortcuts Cra doesn't reserve, like in Chrome, so ⌘F in
+Google Docs works. The [full list](https://crabrowser.app/shortcuts) is on the site.
+
+## Privacy and security
+
+Cra has no account and no server, and the app collects no analytics. Spaces, tabs and the
+archive are plain JSON in `~/Library/Application Support/Cra`. A built-in blocker stops
+requests to more than 22,000 ad and tracker domains.
+
+Pages run in Chromium's sandbox with site isolation, passwords and cookies are encrypted
+with a key in your Keychain, and new Chromium releases are checked daily and shipped as
+signed updates. [crabrowser.app/security](https://crabrowser.app/security) says what is
+and isn't covered. To report a vulnerability, see [SECURITY.md](SECURITY.md).
-⌥⌘I toggles Chrome DevTools docked on the right of the page (drag the divider to resize);
-Inspect Element from the context menu opens it at the clicked node. Each tab keeps its own
-DevTools; the dock follows the selected tab.
+## Support Cra
-## Brand
+Cra is free and open source and has no investors or ads. If it earns a place on your Mac,
+sponsoring it pays for the Chromium updates, the Apple signing and the time it takes to
+keep a browser going. It unlocks nothing in the app, and every feature stays free for
+everyone.
-`brand/` holds the marks; `resources/brand/*.png` are WebKit renders of them (so the
-multiply blends survive) used by `BrandMark`, and `resources/AppIcon.icns` is built from
-`brand/cra-segments-icon.svg` (render at 1024 px, `iconutil`).
+<p align="center">
+ <a href="https://github.com/sponsors/VictorKildahl"><img alt="Sponsor on GitHub" src="docs/assets/sponsor.png" width="272" height="60"></a>
+</p>
-## Website and brand
+<p align="center"><a href="https://crabrowser.app/support">Where the money goes</a></p>
-The marketing site lives in a separate private repository (VictorKildahl/cra-website).
-Logo sources are in `brand/` (see `brand/README.md`); `resources/brand` holds the PNGs the
-app loads and `resources/AppIcon.icns` the app icon.
+## Build from source
-## Developer Mode and shortcuts
+ scripts/build.sh # fetches CEF on first run, builds build/Cra.app
+ scripts/run.sh # build if needed, then open
+ scripts/dev.sh # dev loop: debug CraDev.app, rebuilds + relaunches on save
-⌃D toggles Arc's per-site Developer Mode: the toolbar switches from the friendly centred
-URL (nav buttons at its left) to the full monospace URL with the developer icons, and the
-nav buttons move into the sidebar. Every shortcut can be changed in Settings → Shortcuts
-(click the shortcut, press new keys; Esc cancels, ⌫ removes; conflicts are flagged).
-Overrides live in `keybindings.json` in the app's support folder.
+Needs Xcode 16+ and CMake (`brew install cmake`). [CONTRIBUTING.md](CONTRIBUTING.md)
+covers sending a change, and [docs/development.md](docs/development.md) covers the code
+layout, scripting hooks and test instances.
-## Picture in Picture
+## Licence
-View ▸ Picture in Picture (or "pip" in the command bar, or the context menu on a video) pops the
-page's video out into Arc's floating window: bare 16:9, 6 pt corners, top-right, draggable and
-resizable from its edges. Hovering it shows close, back to tab, play/pause and ±15 s buttons. Leaving a tab whose video is playing pops it
-out automatically (Settings ▸ Tabs, "Enable Picture in Picture when you leave a video tab"), and
-coming back to the tab brings the video home. `open "cra://action/pictureInPicture"` toggles it.
+MIT, see [LICENSE](LICENSE). Arc is a trademark of The Browser Company. Cra is an
+independent project and is not affiliated with it.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..70c9e05
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,35 @@
+# Security
+
+## Reporting a vulnerability
+
+Please report security problems privately through
+[GitHub's private vulnerability reporting](https://github.com/VictorKildahl/cra/security/advisories/new),
+not in a public issue. Include the Cra version (Cra ▸ About Cra), your macOS version, and
+the steps or a page that shows the problem.
+
+Cra is made by one person, so there is no guaranteed turnaround, but reports are read
+within a few days and fixes ship as a signed update that installs on its own. Reporters
+are credited in the release notes unless they'd rather not be.
+
+## Supported versions
+
+Only the latest release is supported. Cra updates itself, and fixes are not backported.
+
+## Scope
+
+In scope: anything Cra adds on top of Chromium, for example
+
+- the `cra://` scheme and what pages or other apps can reach through it
+- import from other browsers, and the passwords and cookies it moves
+- the update feed and signature checks (Sparkle)
+- extensions, native messaging hosts and the Chrome Web Store install flow
+- Cra's patches to CEF (`scripts/cef-patches`) and the switches Cra starts Chromium with
+- passkeys, Safe Storage and other Keychain use
+
+Out of scope: bugs in Chromium itself, which belong with the
+[Chromium project](https://www.chromium.org/Home/chromium-security/reporting-security-bugs/).
+If Cra ships a Chromium version with a known, fixed vulnerability for longer than a few
+days, that is worth an ordinary issue.
+
+Known gaps, listed on [crabrowser.app/security](https://crabrowser.app/security): Cra has
+no Google Safe Browsing, so there are no warnings for known phishing or malware pages.
diff --git a/docs/arc-reverse-engineering.md b/docs/arc-reverse-engineering.md
index 914c29d..915f54b 100644
--- a/docs/arc-reverse-engineering.md
+++ b/docs/arc-reverse-engineering.md
@@ -12,7 +12,7 @@ Legend: [O] observed in shipped artifact or data file, [I] inference, [U] unknow
SpaceStyleEditor, TypeTravel, LittleBrowser, HoverCards...). UI is AppKit: SidebarViewController, SidebarDockViewController,
NSCollectionView layouts, CommandBarTextField, SuggestionsView.
- [O] Web content is embedded Chromium ("User Data/Default" is a Chrome profile: History, Cookies, Extensions, Preferences).
-- [I] So Arc = native chrome + Chromium engine. Cra uses WKWebView instead (design choice, not a copy).
+- [I] So Arc = native chrome + Chromium engine. Cra does the same, with Chromium through CEF.
## Sidebar data model (StorableSidebar.json)
- [O] `sidebar.containers` = [ {global}, {spaces, topAppsContainerIDs, items} ]. Lists are flat [id, object, id, object...].
diff --git a/docs/assets/download.png b/docs/assets/download.png
new file mode 100644
index 0000000..092999e
Binary files /dev/null and b/docs/assets/download.png differ
diff --git a/docs/assets/sponsor.png b/docs/assets/sponsor.png
new file mode 100644
index 0000000..33aa0c4
Binary files /dev/null and b/docs/assets/sponsor.png differ
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..f8ba81a
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,87 @@
+# Developing Cra
+
+Notes for working on the code. How to send a change is in
+[CONTRIBUTING.md](../CONTRIBUTING.md); user-facing docs live in the help centre at
+[crabrowser.app/help](https://crabrowser.app/help).
+
+## Build
+
+ scripts/build.sh # fetches CEF on first run, builds build/Cra.app
+ scripts/build.sh debug # debug build
+ scripts/run.sh # build if needed, then open (--rebuild forces a build)
+ scripts/dev.sh # dev loop: debug CraDev.app, rebuilds + relaunches on save (~4 s)
+
+Requirements: macOS 14+ on Apple silicon, Xcode 16+, CMake (`brew install cmake`), about
+1 GB of disk for CEF and the build products.
+
+`scripts/fetch-cef.sh` pins the CEF version and downloads it into `vendor/cef` (not
+committed). It fetches Cra's own CEF build, made by `scripts/build-cef.sh` with H.264/AAC
+and the patches in `scripts/cef-patches` and published as a `cef-*` release by
+`scripts/publish-cef.sh`; `CEF_URL` points it at Spotify's stock build instead. A daily workflow (`.github/workflows/cef-updates.yml`) opens an
+issue when a newer stable CEF is out; `scripts/update-cef.sh` moves the pin.
+
+## Layout
+
+- `Sources/Cra` — the app: `App` (delegate, key bindings), `Model`, `Services` (sidebar
+ store, persistence, import, updates, extensions, live folders), `UI` (sidebar, command
+ bar, split view, windows, settings, onboarding)
+- `Sources/CraCEF` — Objective-C++ bridge between Swift and CEF
+- `Sources/CraHelper` — Chromium subprocess executable
+- `resources/` — app icon, brand PNGs, the ad and tracker blocklist with its licence notices
+- `scripts/` — build, release, CEF and test tooling; `scripts/clips` records release clips
+- `docs/arc-reverse-engineering.md` — what was learned from Arc and how
+- `docs/release.md` — signing, notarization and the release workflow
+- `vendor/cef` — CEF binary distribution (fetched, not committed)
+
+Data lives in `~/Library/Application Support/Cra`: the sidebar and archive as JSON,
+`keybindings.json`, cached favicons, `chromium.log` and a Chromium profile folder. Delete
+it to start over.
+
+## Running a test instance
+
+Cra is single-instance and the installed copy receives every `cra://` URL, so test a
+build next to your daily Cra with its own data folder and a command file:
+
+ CRA_DATA_DIR=/tmp/cra-test CRA_COMMAND_FILE=/tmp/cra-test.cmd build/Cra.app/Contents/MacOS/Cra &
+ echo "cra://action/newTab" >> /tmp/cra-test.cmd
+
+Every line appended to `CRA_COMMAND_FILE` is handled like a `cra://` URL, including the
+scripting hosts below.
+
+## Scripting hooks
+
+Cra registers the `cra://` scheme so it can be driven from a shell:
+
+ open "cra://action/newTab" # any action id from KeyBindings.swift
+ open "cra://commandbar?query=github" # open the command bar with text
+ open "cra://open?url=https://example.com&background=1"
+ open "cra://open?url=https://example.com&little=1" # in a Little Window
+ open "cra://import?source=arc&archive=1&settings=1" # headless import
+ open "cra://dismiss" # close sheets, command bar, find bar
+
+Links from other apps and browsers only reach `commandbar`, `dismiss` and `open` with an
+http(s) URL; pages inside Cra reach none of them. The rest (`action`, `navigate`, `key`,
+`import`, `debug`) run scripts and DevTools Protocol commands, so they need either
+`defaults write dk.kildahl.cra scriptingURLs -bool YES` or a test instance's
+`CRA_COMMAND_FILE`. See `AppDelegate.isUserFacing` before adding a host.
+
+## Rendering calibration
+
+`open "cra://debug?lift=0&liftInactive=0.75&alpha=1&material=13&state=follows&appearance=dark"`
+changes the vibrancy parameters live (see `Sources/Cra/UI/Tuning.swift`). `material` is the
+raw `NSVisualEffectView.Material` value, `alpha` scales the gradient opacity.
+
+## Brand assets
+
+Logo sources are in `brand/` (see `brand/README.md`). `resources/brand/*.png` are WebKit
+renders of them (so the multiply blends survive) used by `BrandMark`, and
+`resources/AppIcon.icns` is built from `brand/cra-segments-icon.svg` (render at 1024 px,
+`iconutil`). The marketing site lives in a separate private repository.
+
+## Releasing
+
+`scripts/release.sh` builds, signs with a Developer ID, notarizes, and packages a DMG and
+zip into `build/dist`. Pushing a `v*` tag runs the same through GitHub Actions and
+publishes a release. Releases with UI changes get short clips on the release notes first
+(`scripts/clips`, `.claude/skills/release-clips`). See [release.md](release.md) for the
+one-time certificate setup.
diff --git a/docs/screenshots/cra.jpg b/docs/screenshots/cra.jpg
new file mode 100644
index 0000000..9eef794
Binary files /dev/null and b/docs/screenshots/cra.jpg differ