Release: open-source-readiness pass + CVE clear + captcha primitive

.env.example

@@ -24,3 +24,11 @@ UNITY_VALIDATE_LLM_PROVIDERS=true
 
 # Cache LLM responses locally. First run hits the provider; later runs replay.
 UNILLM_CACHE=true
+
+# Optional AntiCaptcha API key (consumed by agent-service's
+# /captcha/solve handler — see agent-service/README.md). Required only
+# if any caller invokes the WebSessionHandle.solve_captcha primitive.
+# Sign up + deposit at https://anti-captcha.com. Without this set, the
+# handler returns 503 anticaptcha_key_missing and callers fall back to
+# their own non-CAPTCHA path.
+ANTICAPTCHA_KEY=

.github/CODEOWNERS

@@ -0,0 +1,23 @@
+# CODEOWNERS for unifyai/unity
+#
+# GitHub uses LAST-MATCH-WINS semantics. The per-path overrides below
+# flag security-sensitive paths in PR descriptions; the reviewer set
+# remains the default pair (the two founding engineers).
+#
+# Either approval satisfies branch protection. GitHub auto-excludes
+# the PR author from the request list, so when one of them opens a
+# PR the other becomes the implicit required reviewer.
+
+# Default reviewers — the two founding engineers.
+*                                  @YushaArif99 @hmahmood24
+
+# Security-sensitive config — flagged so it shows up in PR descriptions.
+/.github/CODEOWNERS                @YushaArif99 @hmahmood24
+/.github/dependabot.yml            @YushaArif99 @hmahmood24
+/.github/workflows/                @YushaArif99 @hmahmood24
+/SECURITY.md                       @YushaArif99 @hmahmood24
+/AGENTS.md                         @YushaArif99 @hmahmood24
+/ARCHITECTURE.md                   @YushaArif99 @hmahmood24
+
+# Secret manager is the highest-blast-radius surface in the codebase.
+/unity/secret_manager/             @YushaArif99 @hmahmood24

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,123 @@
+name: "🐛 Bug report"
+description: Something is broken, crashing, or behaving incorrectly.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+- type: markdown
+  attributes:
+    value: |
+      Thanks for taking the time to file a bug report.
+
+      Before submitting:
+      - Search [existing issues](https://github.com/unifyai/unity/issues) to avoid duplicates.
+      - Try `unity update` and confirm the bug still reproduces.
+      - If this is install-related, run `unity doctor` and include its output below.
+
+- type: textarea
+  id: description
+  attributes:
+    label: What's wrong?
+    description: A clear description of the bug. Include error messages, tracebacks, or screenshots if relevant.
+    placeholder: |
+      What happened? What did you expect to happen instead?
+  validations:
+    required: true
+
+- type: textarea
+  id: reproduction
+  attributes:
+    label: Steps to reproduce
+    description: Minimal steps to trigger the bug. The more specific, the faster we can fix it.
+    placeholder: |
+      1. `unity` from a fresh terminal
+      2. Send the message "..."
+      3. Observe ...
+  validations:
+    required: true
+
+- type: textarea
+  id: expected
+  attributes:
+    label: Expected behavior
+  validations:
+    required: true
+
+- type: textarea
+  id: actual
+  attributes:
+    label: Actual behavior
+    description: Include the full error output if available.
+  validations:
+    required: true
+
+- type: dropdown
+  id: surface
+  attributes:
+    label: Affected surface
+    multiple: true
+    options:
+    - CLI (`unity`)
+    - Voice (`unity --live-voice`)
+    - Installer / setup (`scripts/install.sh`, `unity setup`, `unity doctor`)
+    - Local Orchestra (Docker / Postgres)
+    - Tests (`tests/parallel_run.sh`)
+    - A specific state manager (Contact / Knowledge / Task / Transcript / Guidance / Function / File / Image / Web / Secret / Blacklist / Data)
+    - Actor / CodeAct execution
+    - ConversationManager / steering / interjection
+    - Event bus / observability
+    - Gateway / external comms
+    - Other (specify below)
+  validations:
+    required: true
+
+- type: input
+  id: os
+  attributes:
+    label: Operating system
+    placeholder: macOS 15.2 / Ubuntu 24.04 / Windows 11 WSL2
+  validations:
+    required: true
+
+- type: input
+  id: python
+  attributes:
+    label: Python version
+    description: Output of `.venv/bin/python --version`
+    placeholder: "3.12.7"
+
+- type: input
+  id: unity-commit
+  attributes:
+    label: Unity commit
+    description: Output of `git rev-parse --short HEAD` in the unity repo.
+    placeholder: "aaabf3d4"
+
+- type: textarea
+  id: doctor
+  attributes:
+    label: "`unity doctor` output (recommended)"
+    description: |
+      Paste the full output of `unity doctor`. This catches the majority of install / environment bugs without back-and-forth.
+    render: shell
+
+- type: textarea
+  id: logs
+  attributes:
+    label: Additional logs / traceback
+    description: |
+      Relevant log lines from `logs/unity/`, `logs/orchestra/`, or pytest output if applicable.
+    render: shell
+
+- type: textarea
+  id: root-cause
+  attributes:
+    label: Root-cause analysis (optional)
+    description: |
+      If you've dug in, share file paths, line numbers, and snippets. This dramatically speeds up fixes.
+
+- type: checkboxes
+  id: pr-ready
+  attributes:
+    label: Are you willing to submit a PR?
+    options:
+    - label: I'd like to fix this myself and submit a PR

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: true
+contact_links:
+- name: 💬 Discord
+  url: https://discord.com/invite/sXyFF8tDtm
+  about: For quick questions, install help, and community discussion.
+- name: 📖 Architecture overview
+  url: https://github.com/unifyai/unity/blob/main/ARCHITECTURE.md
+  about: How Unity is designed — read this before opening a design-question issue.
+- name: 🤝 Contributing guide
+  url: https://github.com/unifyai/unity/blob/main/CONTRIBUTING.md
+  about: How to set up the dev environment and submit a PR.
+- name: 🧠 Agent conventions (AGENTS.md)
+  url: https://github.com/unifyai/unity/blob/main/AGENTS.md
+  about: Coding standards, test philosophy, and git workflow.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,74 @@
+name: "✨ Feature request"
+description: Suggest a new capability, manager, primitive, or improvement.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+- type: markdown
+  attributes:
+    value: |
+      Before submitting:
+      - Search [existing issues](https://github.com/unifyai/unity/issues) — someone may have proposed this already.
+      - For new procedural how-tos or executable functions for *your* assistant, consider that `GuidanceManager` and `FunctionManager` are designed to absorb those at runtime, no code change required. Feature requests in this repo are for changes to the runtime itself.
+      - See [`ARCHITECTURE.md`](https://github.com/unifyai/unity/blob/main/ARCHITECTURE.md) for how the manager / primitive boundary works.
+
+- type: textarea
+  id: problem
+  attributes:
+    label: Problem or use case
+    description: What are you trying to do that you can't today? What's the user-facing pain?
+  validations:
+    required: true
+
+- type: textarea
+  id: solution
+  attributes:
+    label: Proposed solution
+    description: |
+      How do you think this should work? Be as concrete as you can — manager API surface, primitive signature, CLI flag, config key.
+  validations:
+    required: true
+
+- type: textarea
+  id: alternatives
+  attributes:
+    label: Alternatives considered
+    description: What other shapes did you consider? Why is the proposed one better?
+
+- type: dropdown
+  id: scope
+  attributes:
+    label: Scope
+    options:
+    - New tool inside an existing manager
+    - New manager (significant — usually needs design discussion first)
+    - New primitive exposed to the Actor
+    - CLI / setup improvement
+    - Voice / fast-brain improvement
+    - Steering / async-tool-loop infrastructure
+    - Observability / event bus
+    - Tests / test infra
+    - Documentation
+    - Other
+  validations:
+    required: true
+
+- type: dropdown
+  id: breaking
+  attributes:
+    label: Is this a breaking change?
+    description: Unity has a zero-backward-compatibility policy — breaking is fine, but flag it.
+    options:
+    - "No"
+    - "Yes — manager API change"
+    - "Yes — event payload / schema change"
+    - "Yes — env var / config change"
+    - "Yes — other"
+  validations:
+    required: true
+
+- type: checkboxes
+  id: pr-ready
+  attributes:
+    label: Contribution
+    options:
+    - label: I'd like to implement this myself and submit a PR

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,76 @@
+<!--
+Thanks for contributing to Unity! Please fill out the sections below.
+For trivial changes (typo fixes, comment-only edits) you can shorten this template — just keep the Summary.
+
+PRs land on `staging`, not `main`. See CONTRIBUTING.md.
+-->
+
+## Summary
+
+<!-- 1–3 sentences: what problem does this PR solve, and why is this the right approach? -->
+
+
+
+## Type of change
+
+<!-- Check all that apply. -->
+
+- [ ] Bug fix (non-breaking change that fixes incorrect behavior)
+- [ ] Feature (non-breaking change that adds functionality)
+- [ ] Refactor (no behavior change)
+- [ ] Breaking change (API or data-model change — Unity has zero-backward-compat policy, but please call it out)
+- [ ] Test-only (no source changes)
+- [ ] Docs / chore / CI
+
+## Areas touched
+
+<!-- Check all that apply. Helps reviewers route. -->
+
+- [ ] Actor / CodeAct
+- [ ] ConversationManager / slow brain
+- [ ] A specific state manager (Contact / Knowledge / Task / Transcript / Guidance / Function / File / Image / Web / Secret / Blacklist / Data / Memory)
+- [ ] Async tool loop (`unity/common/_async_tool/`)
+- [ ] Event bus / observability
+- [ ] Gateway / external comms
+- [ ] Tests / test infra (`tests/`, `conftest.py`, `parallel_run.sh`)
+- [ ] CI / build / packaging
+
+## Test plan
+
+<!--
+How did you verify this? Paste the command(s) you ran and the result.
+
+The default expectation is to run the relevant directory:
+  tests/parallel_run.sh tests/<module>/
+
+For infrastructure changes that are hard to reach via tests, a quick
+verification script under tests/_verify_*.py is encouraged
+(see .cursor/rules/surgical-verification-before-tests.mdc).
+-->
+
+```
+tests/parallel_run.sh tests/...
+```
+
+- [ ] All relevant tests pass locally
+- [ ] If this is a bug fix, I added a regression test (or explained why one isn't feasible)
+
+## Behavior / migration notes
+
+<!--
+- Did this change a public manager API, primitive, or event payload?
+- Are there schema/context changes in Orchestra that need a migration?
+- Any new env vars or config flags? (Update `.env.advanced.example`.)
+- If yes to any of the above, describe upgrade steps.
+-->
+
+None.
+
+## Checklist
+
+- [ ] PR is targeted at `staging` (not `main`)
+- [ ] Followed conventional commit style (`feat(scope):`, `fix(scope):`, `refactor(scope):`, `chore(scope):`, etc.)
+- [ ] No `try/except` added defensively — only around specific, recoverable errors
+- [ ] No "new" / "updated" / "TODO from chat" temporal comments (see `.cursor/rules/no-temporal-comments.mdc`)
+- [ ] No test-specific shortcuts in production code (see `.cursor/rules/no-test-info-in-production-code.mdc`)
+- [ ] Updated `AGENTS.md` / `ARCHITECTURE.md` if I changed architectural conventions

.github/dependabot.yml

@@ -0,0 +1,58 @@
+# Dependabot configuration for unifyai/unity.
+#
+# Scoped to GitHub Actions and the agent-service npm workspace.
+#
+# We deliberately do NOT enable scheduled pip updates: Unity sits on top of
+# three sibling repos (unify, unillm, orchestra-core) wired in via editable
+# uv installs, and we move source-dep pins deliberately rather than on a
+# cadence. CVE-driven security PRs against currently-pinned deps are still
+# delivered via the repo-level "Dependabot security updates" setting
+# (Settings → Code security → Dependabot security updates) — those are
+# fire-on-CVE, not schedule-driven, and that's exactly when we want to
+# move a pin.
+#
+# GitHub Actions and the agent-service npm package are the exceptions:
+# - action pins should be kept fresh (most upstream bumps are themselves
+#   security fixes); Dependabot's grouped weekly PR is low-noise.
+# - agent-service is leaf TypeScript with no Python coupling, so npm
+#   patch/minor bumps are safe to apply on a schedule.
+
+version: 2
+updates:
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "weekly"
+    day: "monday"
+  open-pull-requests-limit: 5
+  labels:
+  - "dependencies"
+  - "github-actions"
+  commit-message:
+    prefix: "chore(actions)"
+    include: "scope"
+  groups:
+      # Batch routine action bumps into one PR per week to reduce noise.
+      # Security updates still open individually and bypass grouping.
+    actions-minor-patch:
+      update-types:
+      - "minor"
+      - "patch"
+
+- package-ecosystem: "npm"
+  directory: "/agent-service"
+  schedule:
+    interval: "weekly"
+    day: "monday"
+  open-pull-requests-limit: 5
+  labels:
+  - "dependencies"
+  - "agent-service"
+  commit-message:
+    prefix: "chore(agent-service)"
+    include: "scope"
+  groups:
+    agent-service-minor-patch:
+      update-types:
+      - "minor"
+      - "patch"