harshmathurx · harshmathurx · Aug 6, 2026 · Aug 6, 2026
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/harshmathurx/OpenNotes/security/advisories/new
+    about: Report vulnerabilities privately. Do not open a public issue for security reports.
+  - name: Questions and support
+    url: https://github.com/harshmathurx/OpenNotes/blob/main/SUPPORT.md
+    about: Check the support guide before opening an issue.
@@ -1,25 +1,54 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to this project are documented here.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- Added a public architecture map for contributors.
+- Added support and governance docs.
+- Added issue-template contact links for security reports and support.
+
+### Changed
+
+- Reworked the README for OSS visitors: current status, download caveat, project map, extension entry points, and contribution paths are now easier to scan.
+- Expanded contributor guidance around architecture boundaries and extension work.
+- Tightened the security policy around local-first risks, native bridge scope, and disclosure expectations.
+
+## [0.1.2] - 2026-08-06
+
+### Fixed
+
+- `Report a bug` now opens a prefilled GitHub issue in the system browser from the Mac app.
+- The web build keeps its existing browser fallback.
+- Package, Tauri config, and Rust crate versions are aligned at `0.1.2`.
+
+## [0.1.1] - 2026-08-05
+
+### Added
+
+- Published the first downloadable Mac build of OpenNotes v2 as an Apple Silicon DMG.
+- Added release assets and a SHA-256 checksum on GitHub Releases.
+- Shipped the v2 workspace surface: markdown editing, workspace home, export, backlinks, templates, AI Co-Writer, and Git Sync.
+
 ## [0.1.0] - 2026-08-05
 
 First public-ready state of the workspace.
 
 ### Added
 
-- **Editor** — Tiptap live-markdown editing with slash menu, wikilinks, bubble menu, zen mode, command palette (`Cmd+K`), and light/dark themes.
-- **Workspace Home** (`Cmd+Shift+H`) — daily journal, scratchpad, kanban, and recent notes.
-- **Styling Studio** — font, size, leading, and canvas width controls, applied instantly and persisted locally.
-- **Local-first storage** — every keystroke lands in IndexedDB first; fully offline-capable; no account.
-- **Extension system** — stable manifest + `activate(ctx)` contract for commands, slash items, and panels (see `docs/extensions.md`). Bundled extensions: Templates, Export (md/html/zip), Backlinks, AI Co-Writer (opt-in, off by default), Git Sync.
-- **Mac app (in active development)** — Tauri v2 desktop app with real `.md` files in a user-picked notes folder, Git Sync via the local git binary and the user's own SSH/agent credentials (VS Code-style, no token custody), and secrets in the macOS Keychain.
-- **AI Co-Writer** — opt-in, bring-your-own Anthropic/OpenAI key or local Ollama; keys encrypted on device with AES-GCM-256.
-
-[Unreleased]: https://github.com/harshmathurx/OpenNotes/compare/v0.1.0...HEAD
+- Tiptap live-markdown editing with slash menu, wikilinks, bubble menu, zen mode, command palette (`Cmd+K`), and light/dark themes.
+- Workspace Home (`Cmd+Shift+H`) with daily journal, scratchpad, kanban, and recent notes.
+- Styling Studio with font, size, leading, and canvas width controls, applied instantly and persisted locally.
+- Local-first storage: every keystroke lands in IndexedDB first; fully offline-capable; no account.
+- Extension system with a stable manifest plus `activate(ctx)` contract for commands, slash items, and panels. Bundled extensions include Templates, Export, Backlinks, AI Co-Writer, and Git Sync.
+- Tauri v2 desktop app with real `.md` files in a user-picked notes folder, Git Sync through the local git binary and the user's own SSH/agent credentials, and secrets in the macOS Keychain.
+- AI Co-Writer: opt-in, bring-your-own Anthropic/OpenAI key or local Ollama; keys encrypted on device with AES-GCM-256.
+
+[Unreleased]: https://github.com/harshmathurx/OpenNotes/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/harshmathurx/OpenNotes/releases/tag/v0.1.2
+[0.1.1]: https://github.com/harshmathurx/OpenNotes/releases/tag/v0.1.1
 [0.1.0]: https://github.com/harshmathurx/OpenNotes/releases/tag/v0.1.0
@@ -1,6 +1,6 @@
 # Contributing to OpenNotes
 
-Thanks for wanting to help. OpenNotes is small on purpose: local-first notes, real files, user-owned sync, opt-in AI, no telemetry.
+Thanks for helping. OpenNotes is small on purpose: local-first notes, real files, user-owned sync, opt-in AI, no telemetry.
 
 Good contributions make that promise sharper.
 
@@ -20,6 +20,17 @@ Good contributions make that promise sharper.
 - Documentation that helps users understand where their data lives.
 - UI polish that makes the app calmer without making it louder.
 
+## Project orientation
+
+Start with the map in [docs/architecture.md](docs/architecture.md). The short version:
+
+- `components/` is the app surface.
+- `core/` holds editor, vault, git, AI, registry, and bridge logic.
+- `extensions/` holds bundled extensions and the starter template.
+- `src-tauri/` holds the Mac desktop shell.
+
+Browser-safe code should not call native APIs directly. Use the bridge modules in `core/bridge/*` and handle the browser fallback clearly.
+
 ## Local setup
 
 ```bash
@@ -34,6 +45,18 @@ For the Mac app:
 pnpm tauri:dev
 ```
 
+## Working on extensions
+
+Extensions are the friendliest contribution path. Use [`extensions/_starter`](extensions/_starter) and read [docs/extensions.md](docs/extensions.md).
+
+A good extension PR usually includes:
+
+- A small manifest and `activate(ctx)` entry point.
+- Pure logic in an `engine.ts` or similar module.
+- Tests for the logic.
+- Honest empty/error states if it adds UI.
+- No secret storage, telemetry, unexpected network calls, or remote code execution.
+
 ## Validation
 
 Run the checks that match your change. For most PRs:
@@ -51,6 +74,8 @@ For desktop/Tauri changes, also run:
 cargo check --manifest-path src-tauri/Cargo.toml
 ```
 
+For extension-only changes, at minimum run the focused test file plus typecheck and lint for the touched paths.
+
 ## Writing the PR
 
 The PR should explain:
@@ -64,4 +89,11 @@ Public PRs are not internal status notes. Write for the next contributor who lan
 
 ## Release notes
 
-If your change ships to users, add a short public-facing release note in the PR. Use `docs/release-writing.md` for the project style.
+If your change ships to users, add a short public-facing release note in the PR. Use [docs/release-writing.md](docs/release-writing.md) for the project style.
+
+## Community
+
+- Use [SUPPORT.md](SUPPORT.md) for help paths.
+- Use [SECURITY.md](SECURITY.md) for private vulnerability reports.
+- Follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+- Maintainer expectations live in [GOVERNANCE.md](GOVERNANCE.md).
@@ -0,0 +1,45 @@
+# Governance
+
+OpenNotes is maintained by [Harsh Mathur](https://github.com/harshmathurx).
+
+The project is small by design. Governance is lightweight until the contributor base needs more structure.
+
+## Maintainer responsibilities
+
+The maintainer is responsible for:
+
+- Reviewing issues and pull requests.
+- Protecting the local-first promise: no account requirement, no telemetry, no hidden custody of notes or tokens.
+- Deciding what belongs in core and what belongs as an extension.
+- Cutting releases and publishing release notes.
+- Handling security reports privately before public disclosure.
+
+## Contribution path
+
+Most changes should start as one of these:
+
+- A bug report with a reproduction.
+- A feature request that explains the workflow.
+- An extension idea.
+- A small pull request with tests or a clear manual validation note.
+
+Large rewrites, hosted services, analytics, cloud sync, token custody, and breaking extension API changes should start as an issue before code is written.
+
+## Decision principles
+
+OpenNotes favors:
+
+- Plain files over proprietary storage.
+- Local git over hosted sync custody.
+- Opt-in AI over ambient AI features.
+- Extensions over core expansion.
+- Honest limitation notes over polished marketing copy.
+- Small, reviewable changes over broad rewrites.
+
+## Becoming a regular contributor
+
+There is no formal role system yet. Contributors who repeatedly ship thoughtful, tested changes may be invited to help triage issues or review extension submissions.
+
+## Security and conduct
+
+Security reports follow [SECURITY.md](SECURITY.md). Community behavior follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
@@ -1,70 +1,87 @@
 # OpenNotes
 
-**Your notes. Real files. Your storage. Your AI.**
+**A Mac-first markdown notes app for people who want real files, local git sync, and opt-in AI.**
 
-OpenNotes is a calm, open-source, local-first markdown workspace. Your notes stay plain `.md` files, sync runs through infrastructure you already own, and AI is opt-in on your own keys. No account, no backend, no telemetry.
+OpenNotes is a local-first workspace for plain `.md` notes. The Mac app writes to a folder you choose, syncs through your own git setup, and keeps AI optional and under your keys. There is no OpenNotes account, backend, telemetry, or token custody.
 
+[![CI](https://github.com/harshmathurx/OpenNotes/actions/workflows/ci.yml/badge.svg)](https://github.com/harshmathurx/OpenNotes/actions/workflows/ci.yml)
+[![Latest release](https://img.shields.io/github/v/release/harshmathurx/OpenNotes?label=latest%20release)](https://github.com/harshmathurx/OpenNotes/releases/latest)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
-[![Local-first](https://img.shields.io/badge/made%20with-local--first-informational.svg)](https://www.inkandswitch.com/local-first/)
-[![Download](https://img.shields.io/github/v/release/harshmathurx/OpenNotes?include_prereleases&label=download)](https://github.com/harshmathurx/OpenNotes/releases)
 
 <img src="screenshots/hero.png" alt="OpenNotes Mac app: a markdown note in the editor beside the Git Sync panel with the sync status banner" width="100%">
 
+## Status
+
+OpenNotes is usable, pre-1.0 software. The core editor, local storage, bundled extensions, and Mac desktop shell work today. The app is still unsigned and not notarized, so macOS shows a first-open warning. Expect sharp edges around packaging, the extension directory, and broader distribution.
+
 ## Download
 
-**OpenNotes is a Mac app.** Get it (Apple Silicon or Intel) from the [Releases page](https://github.com/harshmathurx/OpenNotes/releases).
+Get the latest Mac build from [GitHub Releases](https://github.com/harshmathurx/OpenNotes/releases/latest).
 
-The Mac app is not yet signed with an Apple certificate, so macOS will warn on first open — right-click → Open → Open to proceed. Signing is on the roadmap (see RELEASE.md).
+Current releases ship as DMGs:
 
-The same codebase also runs in a browser (`pnpm dev`) for development and as a tech preview, but the Mac app is the product: it is where real files on disk and git sync live.
+- Apple Silicon: `OpenNotes_<version>_aarch64.dmg`
+- Intel: planned in the release workflow, not always attached to early releases
 
-## Why OpenNotes
+After installing, drag `OpenNotes.app` into Applications. Because the app is not yet Apple-notarized, first launch requires **right-click → Open → Open**. See [RELEASE.md](RELEASE.md) for the safe install path and signing status.
 
-Most note tools ask you to give up at least one of three things: your files, your sync, or your AI. OpenNotes is built on the position that you shouldn't have to give up any of them.
+The browser build (`pnpm dev`) is useful for development and preview. The Mac app is the product surface for real files on disk, git sync, and Keychain-backed secrets.
 
-- **Files** — notes are plain markdown. Obsidian gets this right but is closed source; Notion holds content on its servers.
-- **Sync** — git, through your own local git and credentials. No hosted sync service, no subscription.
-- **AI** — opt-in, on your own Anthropic/OpenAI key or a local Ollama model. Keys are encrypted on device and never touch a server.
+## Why OpenNotes exists
 
-The bet: a small, excellent core plus a clean extension API beats a bloated app.
+Most note apps ask you to compromise on at least one layer:
 
-## What works now
+- Your notes are not normal files.
+- Sync depends on a vendor account.
+- AI requires sending content through someone else's product path.
+- Extensions are powerful but opaque, or safe but too limited.
 
-- **Editor** — Tiptap live-markdown editing, slash menu, wikilinks, bubble menu, zen mode, command palette (`Cmd+K`), light/dark themes.
-- **Workspace Home** (`Cmd+Shift+H`) — daily journal, scratchpad, kanban, recent notes.
-- **Styling Studio** — font, size, leading, and canvas width, applied instantly and persisted locally.
-- **Local-first storage** — every keystroke lands in IndexedDB first; works offline; no account required.
-- **Extensions** — bundled: Templates, Export (md/html/zip), Backlinks, AI Co-Writer (opt-in, off by default), and Git Sync (Mac app).
+OpenNotes takes the boring position: notes should be files, sync should use tools you already trust, and AI should be off until you choose otherwise.
 
-## The Mac app
+## What works now
+
+| Area           | Current behavior                                                                                                         |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Editor         | Tiptap live-markdown editing, slash menu, wikilinks, bubble menu, zen mode, command palette (`Cmd+K`), light/dark themes |
+| Workspace home | Daily journal, scratchpad, kanban, recent notes (`Cmd+Shift+H`)                                                          |
+| Styling        | Font, size, leading, and canvas width controls, persisted locally                                                        |
+| Local storage  | IndexedDB in the web build; real `.md` files in the Mac app                                                              |
+| Extensions     | Templates, Export, Backlinks, AI Co-Writer, Git Sync                                                                     |
+| Git sync       | Uses the local git binary and your existing SSH/agent credentials in the Mac app                                         |
+| AI             | Bring your own Anthropic/OpenAI key or local Ollama; off by default                                                      |
 
-OpenNotes is a Mac app (`src-tauri`, Tauri v2). It is the home of everything that makes the product sovereign:
+## Where data lives
 
-- **Real `.md` files** in a notes folder you pick — grep them, back them up, open them in any editor.
-- **Git Sync** through your local git binary with your own SSH/agent credentials — VS Code-style sync, no tokens, we never see a secret.
-- **AI keys and other secrets** live in the macOS Keychain, not in browser storage.
+- Notes: IndexedDB in the browser build; a folder you choose in the Mac app.
+- Git credentials: your local git and SSH/agent setup. OpenNotes does not hold a GitHub token.
+- AI keys: encrypted on device. The Mac app stores secrets in the macOS Keychain.
+- Telemetry: none.
 
-The web build is the same codebase for development and preview, but the Mac app is the product. It is in active development; expect rough edges.
+Clearing browser site data removes browser-stored notes from that profile. If the notes matter, use the Mac app with a real folder or keep an independent backup.
 
 ## Extensions
 
-The app ships minimal on purpose; capabilities are extensions. Each one is a plain TypeScript object (a manifest plus `activate(ctx)`) that registers commands, slash items, and panels — no `eval`, no remote code. Third-party developers build against the same stable contract the bundled extensions use. See [docs/extensions.md](docs/extensions.md).
+OpenNotes keeps the center small. Capabilities live as extensions: a manifest plus `activate(ctx)` that registers commands, slash items, and panels. Bundled extensions use the same public contract contributors use.
 
-## Where data lives
+Start here:
 
-- **Notes**: IndexedDB in your browser profile on web; real files on disk in the Mac app. There is no OpenNotes backend — note content is never uploaded anywhere by us.
-- **AI keys**: encrypted on device (AES-GCM-256 via WebCrypto on web, Keychain on Mac), never in plaintext, never on a server.
-- **Telemetry**: none. Accounts: none. Token custody: none.
+- [Extension guide](docs/extensions.md)
+- Starter template: [`extensions/_starter`](extensions/_starter)
+- Built-in references: [`extensions/templates`](extensions/templates), [`extensions/backlinks`](extensions/backlinks), [`extensions/export`](extensions/export), [`extensions/gitSync`](extensions/gitSync)
 
-Clearing browser site data removes locally stored notes from that profile — if your notes matter, keep them in a synced folder or an independent copy.
+Extensions are statically imported today. A curated community extension directory is on the roadmap.
 
-## Roadmap
+## Project map
+
+- `app/` and `components/`: Next.js app shell and UI
+- `core/`: editor, vault, storage, git, AI, registry, and bridge logic
+- `extensions/`: bundled extensions and starter template
+- `src-tauri/`: macOS desktop shell and native commands
+- `tests/`: unit and end-to-end coverage
+- `.github/`: CI, release workflow, issue templates, CODEOWNERS, Dependabot
 
-1. Mac app + git sync, hardened end to end.
-2. Community extension directory.
-3. Dropbox / folder-based storage providers.
-4. PWA polish and offline installability.
+For a fuller maintainer map, see [docs/architecture.md](docs/architecture.md).
 
 ## Local development
 
@@ -74,20 +91,49 @@ pnpm install
 pnpm dev
 ```
 
-Then open http://localhost:3000. For the Mac app (once the Tauri toolchain is set up): `pnpm tauri:dev`.
+Open http://localhost:3000.
 
-## Validation commands
+For the Mac app:
 
 ```bash
-pnpm exec eslint .
-pnpm exec tsc --noEmit
+pnpm tauri:dev
+```
+
+You will need the Tauri macOS toolchain installed. The desktop app is the only surface that can use real folders, local git, and Keychain secrets.
+
+## Validation
+
+Run the checks that match your change:
+
+```bash
+pnpm run typecheck
+pnpm run lint
 pnpm exec vitest run
-pnpm exec next build
+pnpm run build
+```
+
+For desktop changes:
+
+```bash
+cargo check --manifest-path src-tauri/Cargo.toml
 ```
 
 ## Contributing
 
-Contributions welcome — extensions most of all. See [CONTRIBUTING.md](CONTRIBUTING.md); new extension ideas have their own friendly issue template ("Extension idea").
+Contributions are welcome, especially small fixes, extension ideas, and reliability work around files, sync, export, and desktop behavior.
+
+- Start with [CONTRIBUTING.md](CONTRIBUTING.md).
+- Report security issues privately via [SECURITY.md](SECURITY.md).
+- For general help, see [SUPPORT.md](SUPPORT.md).
+- Maintainer expectations live in [GOVERNANCE.md](GOVERNANCE.md).
+
+## Roadmap
+
+1. Harden Mac app packaging, signing, and notarization.
+2. Ship a curated community extension directory.
+3. Improve import/export and folder-backed workflows.
+4. Add optional storage providers only where users keep control.
+5. Polish the browser build as a preview/PWA surface.
 
 ## License