diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..6c8840f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,69 @@ +name: Bug report +description: Something broke the companion (or the privacy promise) +title: "[Bug] " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for filing a bug. If this is a **security / privacy** concern + (uploads, API keys, reading tool contents, writing other tools' configs), + please use [SECURITY.md](../SECURITY.md) instead of a public issue. + - type: input + id: macos + attributes: + label: macOS version + placeholder: "14.5" + validations: + required: true + - type: input + id: swift + attributes: + label: Swift version (`swift --version`) + placeholder: "Apple Swift version 6.0" + validations: + required: true + - type: input + id: aihero + attributes: + label: AIhero version (`swift run AIhero --version` or bundled binary) + placeholder: "0.1.0" + validations: + required: false + - type: dropdown + id: codex + attributes: + label: Is Codex CLI installed and logged in? + options: + - "Yes" + - "No" + - "Not sure / N/A" + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + placeholder: | + 1. … + 2. … + 3. … + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + validations: + required: true + - type: textarea + id: extras + attributes: + label: Extra context + description: Logs, screenshots, whether you used `swift run` or a packaged `.app`. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..4039393 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Security / privacy report + url: https://github.com/DevVig/AIhero/security/advisories/new + about: Report uploads, API-key solicitation, or other privacy violations privately. diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000..aaeb808 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,41 @@ +name: Feature idea +description: A fun, collectible idea — not a dashboard knob +title: "[Feature] " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + AIhero's north star is **"fun, not bloat."** Features that feel like an + admin console, telemetry panel, or settings explosion are out of scope. + Privacy constraints in [SECURITY.md](../SECURITY.md) still apply. + - type: textarea + id: idea + attributes: + label: What's the idea? + description: Describe the delight, not the architecture dump. + validations: + required: true + - type: textarea + id: why + attributes: + label: Why does this fit a collectible companion? + placeholder: How does this make forging / unboxing / leveling more fun? + validations: + required: true + - type: checkboxes + id: privacy + attributes: + label: Privacy fit + options: + - label: This stays on-device (no AIhero server, no uploads) + required: true + - label: This does not require pasting an API key into the app + required: true + - label: This does not write into other tools' configs or parse their file contents + required: true + - type: textarea + id: extras + attributes: + label: Extra notes + description: Mockups, MagicPath refs, related issues — optional. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..32363c6 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,17 @@ +## Summary + + + +## Test plan + +- [ ] `swift build` +- [ ] `swift test` +- [ ] `swift run AIhero --render /tmp/aihero-shots` (if UI changed) +- [ ] Manual smoke: forge / unbox / companion (if behavior changed) + +## Privacy checklist + +- [ ] No uploads / no AIhero server calls +- [ ] No API keys solicited or stored in the app +- [ ] No writing into other tools' configs (`~/.codex`, `~/.claude`, etc.) +- [ ] Activity reads stay consent-gated and mtime/presence-only (no file contents) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..740d27d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,31 @@ +name: CI + +on: + push: + branches: [main, master] + pull_request: + branches: [main, master] + +jobs: + build-and-test: + name: Build & Test + runs-on: macos-15 + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Select Xcode 16 (Swift 6) + uses: maxim-lobanov/setup-xcode@v1 + with: + xcode-version: "16.4" + + - name: Show toolchain + run: | + xcodebuild -version + swift --version + + - name: Build + run: swift build + + - name: Test + run: swift test diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..d153287 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,58 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in the +AIhero community a harassment-free experience for everyone, regardless of age, +body size, visible or invisible disability, ethnicity, sex characteristics, +gender identity and expression, level of experience, education, socio-economic +status, nationality, personal appearance, race, caste, color, religion, or +sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Focusing on what is best for the community +- Showing fun, curiosity, and craftsmanship — this is a collectible toy, not a + battlefield + +Examples of unacceptable behavior: + +- The use of sexualized language or imagery, and sexual attention or advances + of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior they deem inappropriate, threatening, offensive, or +harmful. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the project in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by opening a private GitHub security advisory or contacting the +maintainers via the repository. All complaints will be reviewed and investigated +promptly and fairly. + +## Attribution + +This Code of Conduct is adapted from the +[Contributor Covenant](https://www.contributor-covenant.org/), version 2.1. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6bb6c10 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,58 @@ +# Contributing to AIhero + +Thanks for wanting to play with the toy. AIhero is a **fun, on-device collectible** — +not a dashboard, not an admin console. When in doubt: fewer knobs, more delight. + +## Hard rules (please read) + +These are load-bearing product promises. PRs that break them will be declined: + +- **Everything stays on the user's Mac.** No AIhero servers. No uploads. +- **No API keys in the app.** Art goes through the user's own Codex CLI login. +- **Activity sources are read-only** (mtime/presence only) and **consent-gated**. +- **Never write into another tool's config** (`~/.codex`, `~/.claude`, etc.). +- **Fun, not bloat.** Features should feel like a collectible companion. + +Full rationale: [documentation/reference/HANDOFF.md](documentation/reference/HANDOFF.md). + +## Dev loop + +Requires **macOS 14+** and a **Swift 6** toolchain. + +```bash +swift build +swift test +swift run AIhero +swift run AIhero --render /tmp/aihero-shots # offscreen visual QA → PNGs +Scripts/make_app.sh release # → dist/AIhero.app (unsigned OK) +``` + +Notes: + +- `swift build` is the source of truth. SourceKit “cannot find type” noise after + adding a new Swift file is often index lag — rebuild before “fixing” it. +- `--render` shows placeholder glyphs for some native controls offscreen; that + is expected. Prefer eager stacks over `LazyVGrid` for surfaces you want in QA. +- Subprocess art generation is gated on production mode so tests/`--render` + never spawn a real Codex run. + +## Documentation lifecycle + +Non-trivial work: + +1. Plan under `documentation/planned/[category]/` +2. Move to `documentation/active/` while implementing (keep active thin) +3. Move to `documentation/completed/[category]/` when done + +Reference docs (no date prefix) live in `documentation/reference/`. + +## Pull requests + +- Keep PRs focused and small when you can. +- Run `swift test` (and `--render` if you touch UI). +- Fill out the PR template privacy checklist. +- Be kind — see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). + +## Security reports + +See [SECURITY.md](SECURITY.md). Do not file public issues for vulnerabilities. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..df2e8ee --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Jonathan Borgwing / DevVig + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..b88234d --- /dev/null +++ b/README.md @@ -0,0 +1,177 @@ +

+ AIhero collectible roster +

+ +

AIhero

+ +

+ Forge collectible superheroes on your Mac.
+ A tiny menu-bar companion that lives on your desktop, reacts when you work,
+ and levels up as you ship — all on-device, no Dock icon, no cloud. +

+ +

+ CI + MIT License + macOS 14+ + Swift 6 + On-device privacy +

+ +

+ The loop · + Privacy · + Quickstart · + Layout · + Contributing +

+ +--- + +## Meet the companion + +A transparent hero stands on your desktop. The menu bar tracks whether you're +idle, thinking, working, or shipping. Open **My Heroes** to unbox sealed +figures, read dossiers, and evolve portraits as you earn XP. + +

+ Transparent desktop companions +

+ +

+ Three companions on the desktop — procedural fallback art that still feels like a toy. +

+ +--- + +## The loop + +| Step | What happens | +| ---- | ------------ | +| **1. Forge** | Pick the tools you use (Codex, Claude Code, Cursor, Ghostty, cmux, T3 Code). Name your hero. Watch the chamber. | +| **2. Unbox** | A sealed collectible lands on the shelf → full-screen reveal → the hero settles on your desktop. | +| **3. Level up** | Real work earns XP. Hit **Update** to evolve the portrait — same genome, higher tier. | + +

+ Forging chamber +   + Collectible hero boxes +

+ +

+ Hero dossier with origin, powers, and signals +

+ +

+ Chamber → sealed boxes → dossier. Fun first. Knobs last. +

+ +--- + +## Everything stays on your Mac + +This is the product promise — and a hard engineering rule: + +| Promise | What it means | +| ------- | ------------- | +| **No AIhero servers** | Nothing is uploaded. There is no backend. | +| **No API keys in the app** | Ever. We will never ask you to paste one. | +| **Optional bespoke art** | Uses *your* installed [Codex](https://github.com/openai/codex) CLI under *your* login. No Codex? Procedural art still looks great. | +| **Read-only activity** | We may notice **file modification times** on tools you enable. We never open prompt text or source. | +| **Consent-gated** | Turn a source off in Settings → it is not read. | +| **No hook installs** | We never rewrite `~/.codex`, `~/.claude`, `~/.cursor`, or your shell rc. | + +--- + +## Requirements + +- **macOS 14+** +- **Swift 6** toolchain (Xcode 16 / Command Line Tools) +- **Optional:** Codex CLI, logged in — for AI-generated portraits + +--- + +## Quickstart + +```bash +git clone https://github.com/DevVig/AIhero.git +cd AIhero + +swift build +swift test # 52 tests +swift run AIhero # menu-bar ⚡ + desktop companion +``` + +### Package a local `.app` + +```bash +Scripts/make_app.sh release +open dist/AIhero.app +``` + +Unsigned / ad-hoc is fine for daily use. For a signed + notarized DMG (Apple +Developer ID required), see [documentation/reference/RELEASE.md](documentation/reference/RELEASE.md). + +### Visual QA + +```bash +swift run AIhero --render /tmp/aihero-shots +open /tmp/aihero-shots +``` + +Curated README shots live in [`docs/images/`](docs/images/). Full offscreen +surfaces live in [`documentation/reference/screenshots/`](documentation/reference/screenshots/). + +--- + +## Project layout + +```text +Sources/AIhero/ + App/ Menu bar, windows, entry (`--render`, `--version`, signal CLI) + Model/ Heroes, roster, XP / evolution, persistence + Forge/ Deterministic forge + narrated chamber + Art/ Procedural portraits & figures (fallback) + Generation/ Codex harness probe + bespoke art pipeline + Activity/ Read-only ambient signals + optional `aihero signal` + Companion/ Transparent desktop panel + Shelf/ My Heroes, boxes, dossier + Settings/ Consent toggles, launch-at-login + Reveal/ Full-screen unboxing burst +Scripts/ make_app · make_icon · sign_app · release +Tests/ 52 unit tests +docs/images/ README visuals +documentation/ Plans, completed write-ups, engineer hand-off +``` + +Engineer deep-dive: **[documentation/reference/HANDOFF.md](documentation/reference/HANDOFF.md)** +Hard constraints live there — read them before changing privacy-sensitive paths. + +--- + +## Releases + +| Path | Who it's for | +| ---- | ------------ | +| **From source** (`swift run` / `make_app.sh`) | Everyone today — fully supported | +| **Signed + notarized DMG** | Gatekeeper-clean installers — needs your Developer ID + icon PNG ([RELEASE.md](documentation/reference/RELEASE.md)) | + +Current bundle version: **0.1.0** + +--- + +## Contributing + +Contributions welcome. Keep it **fun, not bloat**, and keep it **on-device**. + +- [CONTRIBUTING.md](CONTRIBUTING.md) — build loop, privacy rules, doc lifecycle +- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — be kind +- [SECURITY.md](SECURITY.md) — private reports for privacy / security issues + +PRs should stay green on CI (`swift build` + `swift test` on macOS 15 / Xcode 16). + +--- + +## License + +[MIT](LICENSE) — use it, fork it, forge your own heroes. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b4d124d --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,40 @@ +# Security Policy + +AIhero is an **on-device** macOS companion. The product promise is simple: +nothing leaves your Mac, and the app never asks you to paste an API key. + +## Supported versions + +| Version | Supported | +| ------- | --------- | +| 0.1.x | Yes | +| main | Best effort | + +## Threat model (what we never do) + +Please treat regressions of these as **security bugs**, not product polish: + +1. **No uploads.** AIhero must not send prompts, code, hero data, or telemetry + to an AIhero server (there is none) or any third-party endpoint from app code. +2. **No API keys in the app.** Bespoke art uses the user's own installed Codex + CLI (`codex exec` + their Codex login). The app must never solicit or store + an OpenAI / image API key. +3. **Read-only on other tools.** Activity detection may read **file modification + times / presence** of enabled tools' own logs. It must never open or parse + file contents (no prompt text, no source code). +4. **No writing into other tools.** Never install hooks or rewrite configs under + `~/.codex`, `~/.claude`, `~/.cursor`, shell rc files, etc. +5. **Consent-gated sources.** Disabled sources in Settings must not be read. + +## Reporting a vulnerability + +Please **do not** open a public issue for security-sensitive reports. + +1. Prefer GitHub's **Private vulnerability reporting** on + [DevVig/AIhero](https://github.com/DevVig/AIhero) (Security → Advisories), or +2. Open a minimal private channel with the maintainers if advisories are + unavailable. + +Include: macOS version, AIhero version (`swift run AIhero --version` or the +bundled binary), steps to reproduce, and impact. We will acknowledge reports as +quickly as we can and coordinate a fix before any public disclosure. diff --git a/docs/images/README.md b/docs/images/README.md new file mode 100644 index 0000000..43f6000 --- /dev/null +++ b/docs/images/README.md @@ -0,0 +1,21 @@ +# README images + +Curated, web-sized screenshots used by the root [README.md](../../README.md). + +Regenerate the full offscreen set, then refresh these: + +```bash +swift run AIhero --render documentation/reference/screenshots + +sips -Z 1400 documentation/reference/screenshots/companion.png --out docs/images/companion.png +sips -Z 1400 documentation/reference/screenshots/gallery.png --out docs/images/gallery.png +sips -Z 1400 documentation/reference/screenshots/boxes.png --out docs/images/boxes.png +sips -Z 1400 documentation/reference/screenshots/chamber.png --out docs/images/chamber.png +sips -s format jpeg -s formatOptions 80 -Z 1200 \ + documentation/reference/screenshots/dossier.png --out docs/images/dossier.jpg + +cp docs/images/gallery.png docs/images/hero-roster.png +``` + +Full QA surfaces (including settings / forge control placeholders) live in +[`documentation/reference/screenshots/`](../../documentation/reference/screenshots/). diff --git a/docs/images/boxes.png b/docs/images/boxes.png new file mode 100644 index 0000000..3ec20da Binary files /dev/null and b/docs/images/boxes.png differ diff --git a/docs/images/chamber.png b/docs/images/chamber.png new file mode 100644 index 0000000..a2fb8b3 Binary files /dev/null and b/docs/images/chamber.png differ diff --git a/docs/images/companion.png b/docs/images/companion.png new file mode 100644 index 0000000..76b1bdb Binary files /dev/null and b/docs/images/companion.png differ diff --git a/docs/images/dossier.jpg b/docs/images/dossier.jpg new file mode 100644 index 0000000..2277ae4 Binary files /dev/null and b/docs/images/dossier.jpg differ diff --git a/docs/images/gallery.png b/docs/images/gallery.png new file mode 100644 index 0000000..8d45fc4 Binary files /dev/null and b/docs/images/gallery.png differ diff --git a/docs/images/hero-roster.png b/docs/images/hero-roster.png new file mode 100644 index 0000000..8d45fc4 Binary files /dev/null and b/docs/images/hero-roster.png differ diff --git a/documentation/active/.gitkeep b/documentation/active/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/documentation/active/2026-07-17_aihero-native-mvp.md b/documentation/completed/milestones/2026-07-17_aihero-native-mvp.md similarity index 90% rename from documentation/active/2026-07-17_aihero-native-mvp.md rename to documentation/completed/milestones/2026-07-17_aihero-native-mvp.md index c2b061a..6cdf1ca 100644 --- a/documentation/active/2026-07-17_aihero-native-mvp.md +++ b/documentation/completed/milestones/2026-07-17_aihero-native-mvp.md @@ -1,6 +1,6 @@ # Task: AIhero — Native macOS Collectible Companion (MVP v0.1) **Date Started**: 2026-07-17 -**Status**: In Progress (core loop functional) +**Status**: Completed (MVP core loop shipped; see production-hardening + activity-signals for later phases) **Agent Lead**: 💻 Frontend / ⚙️ Backend ## Plan @@ -94,10 +94,10 @@ open dist/AIhero.app # menu-bar ⚡ appears; first run opens the she `Support/RenderHarness.swift`. ## Notes for Next Engineer -- **Not yet built (future scope)**: real consented connectors + deterministic redaction feeding the - forge (currently `Source` toggles are flavor inputs only); real harness lifecycle tracking to - replace the simulated `WorkState`; hero evolution (level/xp/story chapters); per-pixel companion - hit-testing (window is currently a snug bounding box); "Jump to active app" routing. -- **Screenshots of the live window** couldn't be captured here (no Screen Recording permission in - this environment); verification used offscreen rendering + a confirmed live launch. -- Git initialized; **not committed** (awaiting user go-ahead). +- **Shipped after this MVP note:** read-only ambient activity + earned evolution ("Update"), + bespoke Codex art pipeline, production hardening, open-source repo front door. See + `documentation/completed/` and `documentation/reference/HANDOFF.md`. +- **Still future scope:** per-pixel companion hit-testing; "Jump to active app" routing; + full Hatch-style atlas animation (planned art pipeline). +- Verification used `--render` offscreen PNGs + live launches; screenshots live in + `documentation/reference/screenshots/`. diff --git a/documentation/active/2026-07-18_production-hardening.md b/documentation/completed/milestones/2026-07-18_production-hardening.md similarity index 98% rename from documentation/active/2026-07-18_production-hardening.md rename to documentation/completed/milestones/2026-07-18_production-hardening.md index 8537654..e52e43c 100644 --- a/documentation/active/2026-07-18_production-hardening.md +++ b/documentation/completed/milestones/2026-07-18_production-hardening.md @@ -1,6 +1,6 @@ # Task: Production Hardening **Date Started**: 2026-07-18 -**Status**: In Progress +**Status**: Completed (Phases A–F done; signed/notarized DMG remains cert-gated — see RELEASE.md) **Agent Lead**: 🏗️⚙️ ## Plan diff --git a/documentation/planned/features/2026-07-18_ai-hero-art-pipeline.md b/documentation/planned/features/2026-07-18_ai-hero-art-pipeline.md index 2180cca..fd87e17 100644 --- a/documentation/planned/features/2026-07-18_ai-hero-art-pipeline.md +++ b/documentation/planned/features/2026-07-18_ai-hero-art-pipeline.md @@ -1,6 +1,6 @@ # Task: Bespoke per-user hero generation via the user's own harness (Hatch-style) **Date Started**: 2026-07-18 -**Status**: Planning (awaiting approval) +**Status**: Planning (post-v0.1 — not activated for the open-source launch) **Agent Lead**: 🏗️ Architect / ⚙️ Backend / 🎨 Designer **Supersedes** the earlier "authoring-time bundled art pack" draft of this same file. diff --git a/documentation/reference/HANDOFF.md b/documentation/reference/HANDOFF.md index 0e7aec2..4ac92ba 100644 --- a/documentation/reference/HANDOFF.md +++ b/documentation/reference/HANDOFF.md @@ -201,16 +201,25 @@ Full detail + rationale: `documentation/completed/features/2026-07-18_unified-ac cert + a MagicPath icon PNG. - **Phase F complete:** read-only ambient activity reader + earned manual "Update" evolution. -**In-flight active docs:** `documentation/active/2026-07-17_aihero-native-mvp.md` and -`2026-07-18_production-hardening.md` (Phase F line now checked off there). +**Completed docs (closed for v0.1):** MVP + production-hardening live under +`documentation/completed/milestones/`. Phase F write-up: +`documentation/completed/features/2026-07-18_unified-activity-signals.md`. + +**Open-source front door:** root `README.md`, MIT `LICENSE`, `CONTRIBUTING.md`, +`SECURITY.md`, `CODE_OF_CONDUCT.md`, `.github/` CI + issue/PR templates, +`documentation/reference/RELEASE.md`, and `--render` shots in +`documentation/reference/screenshots/`. **Deferred / tracked (not blockers):** - Unix-domain-socket fast path for the ping transport (currently atomic-file). - Type-only reads to distinguish thinking / waiting / plan-ready (needs its own explicit consent step). - A forge "gather"-stage wiring test. -- Signed/notarized DMG is gated on the user's Apple Developer cert being available. +- Signed/notarized DMG is gated on the user's Apple Developer cert being available + (procedure documented in `documentation/reference/RELEASE.md`). - Evolution tunables (`xpGrant=10`, `xpGrantInterval=15s`, `xpForNextLevel=level*30`) are sensible defaults but **haven't been felt out in a long live session** — expect to retune the pace. +- Full Hatch-style atlas animation / discovery worker — still in + `documentation/planned/features/2026-07-18_ai-hero-art-pipeline.md` (post-v0.1). - **Orphan test PNG** at `~/Library/Application Support/AIhero/art/40C360C3-2DED-4571-A42F-D09B94D58C62.png` — left from a render; the owner has **not** approved deleting it. Do not delete without confirming. @@ -218,9 +227,9 @@ Full detail + rationale: `documentation/completed/features/2026-07-18_unified-ac ## 8. Gotchas / traps (things that will waste your afternoon) -1. **The repo has NO git commits yet.** Everything is untracked (`git status` shows only `??` - entries). Before doing anything destructive, get an initial commit in. There is no history to fall - back on right now. +1. **History is thin but real.** The repo has an initial commit and an open-source packaging + layer on top; treat `main` as the source of truth and prefer small, reviewable commits over + rewriting history. 2. **SourceKit index-lag false positives.** After creating a new Swift file you'll see editor/ diagnostic errors like *"Cannot find type 'X' in scope"* or *"Cannot infer contextual base in reference to member 'idle'"*. These are **not real** — `swift build` is the source of truth and @@ -253,13 +262,16 @@ prefix** and are continually updated. Work items are `YYYY-MM-DD_description.md` Start non-trivial work in **plan mode**, write the plan to `planned/`, get approval, then move it to `active/` while implementing and log changes as you go. The most useful reading order for a newcomer: -1. This file. -2. `documentation/completed/features/2026-07-18_unified-activity-signals.md` (Phase F, the newest and +1. Root `README.md` (product pitch + quickstart). +2. This file. +3. `documentation/completed/features/2026-07-18_unified-activity-signals.md` (Phase F, the newest and most nuanced subsystem, with the full privacy rationale). -3. `documentation/active/2026-07-18_production-hardening.md` (what "production-ready" meant here). -4. `documentation/completed/features/2026-07-18_forging-experience.md` (the forge/reveal UX). -5. `documentation/planned/features/2026-07-18_ai-hero-art-pipeline.md` (where the art pipeline is - headed). +4. `documentation/completed/milestones/2026-07-18_production-hardening.md` (what "production-ready" + meant for v0.1). +5. `documentation/completed/features/2026-07-18_forging-experience.md` (the forge/reveal UX). +6. `documentation/planned/features/2026-07-18_ai-hero-art-pipeline.md` (where the art pipeline is + headed — post-v0.1). +7. `documentation/reference/RELEASE.md` (tags + cert-gated notarization). --- @@ -267,8 +279,11 @@ Start non-trivial work in **plan mode**, write the plan to `planned/`, get appro 1. `swift build && swift test` (expect 52/0) and `swift run AIhero` — get the companion on your desktop and forge a hero to build intuition. -2. `swift run AIhero --render /tmp/shots` and browse the PNGs — the fastest way to see every surface. -3. **Make the initial git commit** (see gotcha #1). -4. Live-test the evolution pace: work for a while with Codex/Claude Code enabled, watch XP accrue, hit +2. Browse `documentation/reference/screenshots/` (or re-run + `swift run AIhero --render documentation/reference/screenshots`) — the fastest way to see every + surface. +3. Live-test the evolution pace: work for a while with Codex/Claude Code enabled, watch XP accrue, hit "Update," and confirm the re-forge feels good. Retune the XP tunables to taste. +4. When Apple Developer credentials + a MagicPath icon PNG are ready, cut a notarized DMG per + `RELEASE.md` and attach it to a GitHub Release. 5. When you touch anything that deploys or ships, re-read §2 — the privacy promises are the product. diff --git a/documentation/reference/RELEASE.md b/documentation/reference/RELEASE.md new file mode 100644 index 0000000..79a917e --- /dev/null +++ b/documentation/reference/RELEASE.md @@ -0,0 +1,66 @@ +# Releasing AIhero + +## Versioning + +The shipped bundle version lives in [`Scripts/make_app.sh`](../../Scripts/make_app.sh) +(`CFBundleShortVersionString` / `CFBundleVersion`, currently `0.1.0`). + +The running binary reports that string via `AIhero --version`. A bare +`swift run` build falls back to `0.1-dev` when no Info.plist is present. + +## Open-source tag (no Apple cert required) + +1. Confirm green CI and local proof: + + ```bash + swift build && swift test + Scripts/make_app.sh release + dist/AIhero.app/Contents/MacOS/AIhero --version # expect 0.1.0 + ``` + +2. Bump the version strings in `Scripts/make_app.sh` if needed. +3. Commit, tag, push: + + ```bash + git tag -a v0.1.0 -m "AIhero v0.1.0" + git push origin HEAD --tags + ``` + +4. Optional: attach an unsigned `dist/AIhero.app` zip to the GitHub Release for + curious builders. Prefer pointing people at `swift run` / `make_app.sh`. + +## Signed + notarized DMG (cert-gated) + +Requires: + +- Apple **Developer ID Application** certificate installed in the keychain +- One-time Notary credentials: + + ```bash + xcrun notarytool store-credentials AIhero \ + --apple-id "you@example.com" \ + --team-id TEAMID \ + --password "app-specific-password" + ``` + +- A square app icon PNG (e.g. from MagicPath), **or** an existing + `Scripts/AppIcon.icns` + +Then: + +```bash +# Icon PNG → .icns is handled inside release.sh when you pass a PNG path +DEVELOPER_ID_APP="Developer ID Application: Your Name (TEAMID)" \ + Scripts/release.sh path/to/icon.png +``` + +`Scripts/release.sh` orchestrates icon → `make_app.sh release` → +`sign_app.sh` (hardened runtime, notarize, staple, DMG). + +Attach the resulting DMG to the GitHub Release. Do **not** commit secrets, +`.p12` files, or notary passwords to the repo. + +## Privacy reminder + +Shipping a binary does not change the threat model: no uploads, no API keys in +the app, read-only consent-gated activity. See [SECURITY.md](../../SECURITY.md). diff --git a/documentation/reference/screenshots/README.md b/documentation/reference/screenshots/README.md new file mode 100644 index 0000000..6fecc5e --- /dev/null +++ b/documentation/reference/screenshots/README.md @@ -0,0 +1,10 @@ +# Screenshots + +Generated by the offscreen harness: + +```bash +swift run AIhero --render documentation/reference/screenshots +``` + +These PNGs power the root README and visual QA. Native controls may show +placeholder glyphs offscreen — expected; they render correctly in the live app. diff --git a/documentation/reference/screenshots/boxes.png b/documentation/reference/screenshots/boxes.png new file mode 100644 index 0000000..105b904 Binary files /dev/null and b/documentation/reference/screenshots/boxes.png differ diff --git a/documentation/reference/screenshots/chamber-builtin.png b/documentation/reference/screenshots/chamber-builtin.png new file mode 100644 index 0000000..c24bc46 Binary files /dev/null and b/documentation/reference/screenshots/chamber-builtin.png differ diff --git a/documentation/reference/screenshots/chamber-failed.png b/documentation/reference/screenshots/chamber-failed.png new file mode 100644 index 0000000..17a0290 Binary files /dev/null and b/documentation/reference/screenshots/chamber-failed.png differ diff --git a/documentation/reference/screenshots/chamber.png b/documentation/reference/screenshots/chamber.png new file mode 100644 index 0000000..0dcf398 Binary files /dev/null and b/documentation/reference/screenshots/chamber.png differ diff --git a/documentation/reference/screenshots/companion.png b/documentation/reference/screenshots/companion.png new file mode 100644 index 0000000..5feaf3e Binary files /dev/null and b/documentation/reference/screenshots/companion.png differ diff --git a/documentation/reference/screenshots/dossier-evolving.png b/documentation/reference/screenshots/dossier-evolving.png new file mode 100644 index 0000000..6953d28 Binary files /dev/null and b/documentation/reference/screenshots/dossier-evolving.png differ diff --git a/documentation/reference/screenshots/dossier-progress.png b/documentation/reference/screenshots/dossier-progress.png new file mode 100644 index 0000000..a8f431b Binary files /dev/null and b/documentation/reference/screenshots/dossier-progress.png differ diff --git a/documentation/reference/screenshots/dossier-ready.png b/documentation/reference/screenshots/dossier-ready.png new file mode 100644 index 0000000..5c2e67d Binary files /dev/null and b/documentation/reference/screenshots/dossier-ready.png differ diff --git a/documentation/reference/screenshots/dossier.png b/documentation/reference/screenshots/dossier.png new file mode 100644 index 0000000..1990235 Binary files /dev/null and b/documentation/reference/screenshots/dossier.png differ diff --git a/documentation/reference/screenshots/forge.png b/documentation/reference/screenshots/forge.png new file mode 100644 index 0000000..fb0d8ca Binary files /dev/null and b/documentation/reference/screenshots/forge.png differ diff --git a/documentation/reference/screenshots/gallery.png b/documentation/reference/screenshots/gallery.png new file mode 100644 index 0000000..6a1f74f Binary files /dev/null and b/documentation/reference/screenshots/gallery.png differ diff --git a/documentation/reference/screenshots/settings.png b/documentation/reference/screenshots/settings.png new file mode 100644 index 0000000..de6f206 Binary files /dev/null and b/documentation/reference/screenshots/settings.png differ diff --git a/documentation/reference/screenshots/shelf.png b/documentation/reference/screenshots/shelf.png new file mode 100644 index 0000000..8b888e8 Binary files /dev/null and b/documentation/reference/screenshots/shelf.png differ