Open source preparation: licensing, credential externalization, and contributor docs

.github/CODEOWNERS

@@ -0,0 +1,15 @@
+# Edited by Claude Opus 5 (Anthropic) on 2026-08-13
+#
+# Default owner for everything in the repository.
+* @ActuallyTaylor
+
+# Anything touching credentials, signing, licensing, or the release pipeline should always get an explicit look, even once other reviewers are added above.
+/Config.xcconfig                    @ActuallyTaylor
+/Config.local.example.xcconfig      @ActuallyTaylor
+/LICENSE                            @ActuallyTaylor
+/NOTICE                             @ActuallyTaylor
+/TRADEMARK.md                       @ActuallyTaylor
+/SECURITY.md                        @ActuallyTaylor
+/scripts/                           @ActuallyTaylor
+/.github/workflows/                 @ActuallyTaylor
+/Minna.xcodeproj/                   @ActuallyTaylor

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,86 @@
+# Edited by Claude Opus 5 (Anthropic) on 2026-08-13
+name: Bug report
+description: Something in Minna isn't working the way it should
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report this.
+
+        **If this is a security or privacy vulnerability, please stop and read [SECURITY.md](https://github.com/impel-intelligence/Minna/blob/main/SECURITY.md) instead — those should be reported privately, not in a public issue.**
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect, and what did you get instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Add a folder containing ...
+        2. Open Ask Minna and ask ...
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: input
+    id: minna-version
+    attributes:
+      label: Minna version
+      description: Found under Minna → About.
+      placeholder: "0.13.1"
+    validations:
+      required: true
+
+  - type: input
+    id: macos-version
+    attributes:
+      label: macOS version
+      placeholder: "26.1"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-source
+    attributes:
+      label: How did you install Minna?
+      options:
+        - Direct download / Sparkle
+        - Mac App Store
+        - Built from source
+    validations:
+      required: true
+
+  - type: dropdown
+    id: provider
+    attributes:
+      label: Which AI provider were you using?
+      description: If the bug isn't provider-related, pick "Not applicable".
+      options:
+        - Not applicable
+        - Anthropic (Claude)
+        - OpenAI
+        - Google Gemini
+        - Ollama
+        - Apple Foundation Models (on-device)
+        - MLX (on-device)
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: |
+        Minna logs to Console.app — filter by the Minna process. Paste anything relevant here.
+
+        **Please review before pasting.** Logs may include file names or paths from your indexed documents. Redact anything you would rather not publish.
+      render: text
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,9 @@
+# Edited by Claude Opus 5 (Anthropic) on 2026-08-13
+blank_issues_enabled: false
+contact_links:
+  - name: Security or privacy vulnerability
+    url: https://github.com/impel-intelligence/Minna/security/advisories/new
+    about: Report privately, not as a public issue. See SECURITY.md.
+  - name: Question or general support
+    url: mailto:support@tryminna.com
+    about: For help using Minna rather than a bug in it.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,37 @@
+# Edited by Claude Opus 5 (Anthropic) on 2026-08-13
+name: Feature request
+description: Suggest something Minna should be able to do
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: |
+        Describe the situation you're in, not the solution you have in mind. Understanding the underlying need usually leads to a better feature than implementing the first idea.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like Minna to do?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What have you tried instead?
+      description: Workarounds you're using today, or other tools that solve this well.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Would you be interested in implementing this?
+      description: Entirely optional — proposals are welcome without it.
+      options:
+        - label: I'd be willing to open a pull request for this
+          required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+<!-- Edited by Claude Opus 5 (Anthropic) on 2026-08-13 -->
+
+## What does this change?
+
+<!-- Describe the change and, more importantly, why it's needed. If it fixes an open issue, write "Fixes #123" so GitHub links them. -->
+
+## How was it tested?
+
+<!-- What did you actually run? Manual steps are fine — say what you did. -->
+
+## Checklist
+
+- [ ] I updated `CHANGELOG.md` under `## [Unreleased]`, written for a Minna user *(skip only if this change has no user-visible effect)*
+- [ ] My commits are signed off (`git commit -s`) per the DCO in [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [ ] The build succeeds and existing tests pass
+- [ ] I did not commit credentials, an Apple Team ID, or anything from `Config.local.xcconfig`
+- [ ] If I used an AI assistant, I've said so below and reviewed the output myself
+
+## Anything else?
+
+<!-- Trade-offs you weighed, things you're unsure about, follow-up work you're deliberately leaving out. Reviewers find this more useful than a clean summary that hides the rough edges. -->

.github/review-guidelines.md

@@ -0,0 +1,83 @@
+# Code review guidelines
+
+<!-- Edited by Claude Opus 5 (Anthropic) on 2026-08-13 -->
+
+Project-specific criteria for the automated reviewer in `.github/workflows/claude-code-review.yml`, and a useful checklist for human reviewers too.
+
+These are **in addition to** ordinary code review. Correctness, clarity, and test coverage still matter; this file covers the things specific to Minna that are easy to miss and expensive to discover after a release.
+
+Report only what a change actually warrants. A one-line bug fix should not attract a lecture about trademark policy. If nothing in a section applies, say nothing about it.
+
+## Licensing, NOTICE, and TRADEMARK
+
+Minna is Apache-2.0 and commercially distributed, so licensing drift is a real cost rather than a formality. Flag a PR when:
+
+- **A new third-party component is vendored into the repository** — a binary framework, a bundled model, copied source, an icon set, a font — and `NOTICE` is not updated to record it. Vendored code carries its own license, and most licenses require the notice travel with the code.
+- **Code is copied from an external source** (Stack Overflow, a blog, another project) without an attribution comment naming the source and its license. Stack Overflow answers are CC BY-SA, which is not Apache-2.0. See `Minna/objc/CatchException.m` for the expected form.
+- **A new local Swift package is added** without an Apache-2.0 `LICENSE` file of its own.
+- **A dependency is added whose license is not Apache-2.0-compatible.** MIT, BSD, and Apache-2.0 are fine. GPL, LGPL, AGPL, and source-available licenses (BUSL, SSPL, PolyForm) are not, and need a decision before merge.
+- **New brand assets are added** — a logo, an app icon, a wordmark — and `TRADEMARK.md` still lists only the old ones. That file enumerates what a fork must replace, so it has to stay current or it stops being useful.
+- **The product or company name changes**, or a new name is introduced, without `TRADEMARK.md` and `NOTICE` following.
+- **`LICENSE` is edited.** It is verbatim canonical Apache-2.0 and should not be modified. The same goes for `Frameworks/Sparkle.framework/LICENSE` and `CODE_OF_CONDUCT.md`, which are verbatim third-party text.
+- **A copyright header is removed or reassigned.** Attribution gets added alongside, never replaced.
+
+## Secrets and configuration
+
+- No credentials, API keys, tokens, DSNs, or Apple Team IDs in tracked files. They belong in `Config.local.xcconfig`, which is gitignored.
+- `Config.xcconfig` must keep every value **blank**. It is committed, and a populated value there ships credentials to everyone. Real values go only in `Config.local.xcconfig`.
+- New telemetry or network calls must fail closed when unconfigured, matching `BuildConfiguration.swift`: absent configuration means the feature is off, not that it falls back to a default endpoint.
+- Any new network destination must be added to the list in `SECURITY.md`. That list is a promise to users about what leaves their machine, and an undocumented endpoint makes it false.
+- Watch for secrets passed as command-line arguments in scripts and workflows — they leak into process listings and logs. Use environment variables.
+- GitHub Actions workflows that consume secrets must stay gated to trusted actors, and must not switch from `pull_request` to `pull_request_target`, which would expose secrets to fork code.
+
+## Privacy
+
+Minna's central claim is that documents and chats stay local. Flag anything that could weaken it:
+
+- Document contents, chat contents, file paths, or index data being sent anywhere.
+- Telemetry that grows beyond aggregate counts, or that could carry user content in an event property or error message.
+- `sendDefaultPii` being enabled, or PII scrubbing being weakened.
+- Logging that writes document contents or full paths, since users are asked to paste logs into bug reports.
+
+## Documentation currency
+
+Flag when:
+
+- A user-visible feature changes and `README.md` still describes the old behavior.
+- An AI provider is added or removed and the provider lists in `README.md`, `SECURITY.md`, and `docs/ARCHITECTURE.md` are not updated.
+- A package is added, removed, or substantially restructured and `docs/ARCHITECTURE.md` still describes the old layout, including its "where to look" table.
+- The build or setup process changes and `CONTRIBUTING.md` still gives the old steps.
+- The minimum macOS or Xcode version changes and the requirements in `README.md` and `CONTRIBUTING.md` do not follow.
+
+## Changelog
+
+- Every user-facing change needs an entry under `## [Unreleased]` in `CHANGELOG.md`, in Keep a Changelog format.
+- Entries should be written for a Minna user, not a developer reading the diff. "Fixed a crash when opening a malformed database" is right; "Fixed nil unwrap in IrisDBController" is not.
+- Internal refactors with no user-visible effect don't need one — don't insist.
+
+## Agent attribution
+
+Per `AGENTS.md`, AI-authored work identifies itself. Flag when:
+
+- A file created or meaningfully edited by an agent has no attribution comment in its header.
+- A doc comment written by an agent lacks its attribution line.
+- A commit authored by an agent lacks a `Co-Authored-By` trailer naming the specific model.
+- An agent added a `Signed-off-by` line for itself. DCO sign-off belongs to the human submitting the work.
+- `CLAUDE.md` was replaced with a regular file instead of remaining a symlink to `AGENTS.md`.
+
+## Formatting
+
+- Prose must not be hard wrapped — paragraphs, comments, doc comments, and commit bodies are single continuous lines. The exception is verbatim external text, where the original wrapping is preserved.
+- Match the surrounding code's style. SwiftLint and SwiftFormat cover the rest.
+- Use `SFSafeSymbols` (`systemSymbol:`) rather than `Image(systemName:)`.
+
+## Build and release integrity
+
+- Changes to `Minna.xcodeproj/project.pbxproj` that reintroduce a hardcoded `DEVELOPMENT_TEAM`, or that drop the `baseConfigurationReference` to `Config.xcconfig`, silently defeat the credential externalization. Inline `buildSettings` override an xcconfig.
+- The `SPARKLE` compilation condition must keep Sparkle out of App Store builds.
+- Changes to `scripts/release.sh` deserve close attention: it signs, notarizes, and uploads.
+- New Swift files land automatically via file-system synchronized groups. A manual `PBXFileReference` addition for a source file usually indicates a mistake.
+
+## Extending this file
+
+Add a section when a class of mistake becomes worth catching automatically. Keep each item concrete enough to check against a diff — "flag when X changes but Y doesn't" is actionable; "ensure good architecture" is not. Sections are independent, so new feature areas can be appended without disturbing what's here.

.github/workflows/claude-code-review.yml

@@ -12,11 +12,10 @@ on:
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    # Restricted to an explicit allowlist of logins, currently just @ActuallyTaylor, since this job spends CLAUDE_CODE_OAUTH_TOKEN. This is a hardcoded login check rather than a permission or role check, so it does not widen automatically when a collaborator is added — extend the condition below to grant access.
+    #
+    # NOTE: this workflow uses `pull_request` rather than `pull_request_target`, which is the safe choice — a pull request from a fork runs without access to repository secrets. The consequence is that this job cannot review fork pull requests at all, and will simply not run on them. That is expected behaviour, not a misconfiguration. Switching to `pull_request_target` to "fix" it would expose secrets to untrusted code from forks.
+    if: github.actor == 'ActuallyTaylor'
 
     runs-on: ubuntu-latest
     permissions:
@@ -38,7 +37,13 @@ jobs:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
           plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          # The slash command runs the standard review. The paragraph after it adds Minna's own criteria, which live in .github/review-guidelines.md so they are version controlled and reviewable rather than buried in this workflow. Extend that file, not this prompt.
+          prompt: |
+            /code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}
+
+            Additionally, read `.github/review-guidelines.md` and review this pull request against the project-specific criteria it defines. They cover licensing and the currency of NOTICE and TRADEMARK.md, secrets and build configuration, Minna's privacy guarantees, documentation drift, CHANGELOG entries, agent attribution, and release integrity.
+
+            Apply those criteria only where the diff actually warrants it — a small fix should not attract commentary on sections it does not touch. Where a guideline is violated, name the specific file that needs updating and why.
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options
 

.github/workflows/claude.yml

@@ -12,11 +12,14 @@ on:
 
 jobs:
   claude:
+    # Restricted to an explicit allowlist of logins, currently just @ActuallyTaylor. This is a hardcoded login check rather than a permission or role check, so it does not widen automatically when a collaborator is added — extend the condition below to grant access. This job spends CLAUDE_CODE_OAUTH_TOKEN, so on a public repository an unrestricted trigger would let any GitHub user run it by leaving a comment.
     if: |
-      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
-      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+      github.actor == 'ActuallyTaylor' && (
+        (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+        (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+      )
     runs-on: ubuntu-latest
     permissions:
       contents: read