diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md new file mode 100644 index 0000000..1202b3a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -0,0 +1,33 @@ +--- +name: Bug report +about: Something installed/runs but doesn't behave as expected +title: "[bug] " +labels: bug +--- + +## What happened + + +## Steps to reproduce +1. +2. +3. + +## Environment +- macOS version: +- Claude Code version: +- brain-in-a-box commit: +- Bun version: + +## Logs / output +
+Click to expand + +``` +paste relevant output here — install.sh transcript, ~/.gbrain/nightly.log, test-hooks.sh output, etc. +``` + +
+ +## What you've already tried + diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md new file mode 100644 index 0000000..2037181 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.md @@ -0,0 +1,30 @@ +--- +name: Feature request / idea +about: Something brain-in-a-box doesn't do yet that you'd want +title: "[feat] " +labels: enhancement +--- + +## What problem does this solve + + +## Proposed approach (optional) + + +## Who benefits +- [ ] Solo users (personal vault) +- [ ] Team users (company brain mode) +- [ ] Agent developers (skill authors) +- [ ] Other: + +## Alignment check + +- [ ] Does NOT require a server (local-first) +- [ ] Does NOT add telemetry/phone-home +- [ ] Does NOT lock users into a specific provider +- [ ] Stays compatible with gstack / openclaw / Hermes / plain Claude Code + +If any unchecked: explain why it's worth the trade-off. + +## Existing alternatives + diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..18d7f7f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,41 @@ +# Changelog + +All notable changes to brain-in-a-box. + +Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). + +## [Unreleased] + +_Nothing yet — open an issue to suggest._ + +## [0.1.0] — 2026-05-26 — Initial public release + +The first public-OSS day. The product was built and dogfooded privately the day before; today it went public after a multi-layer scan (file content + full git history + tier names like personal contacts) confirmed zero personal info leaks. + +### Added +- **Vault skeleton with team-first folders**: `Profile/`, `Team/` (humans), `Agents/` (AI agents as first-class teammates), `Decisions/` (one file per locked-in choice), `Skills/` (gstack SKILL.md format), plus existing `Journal/`, `Projects/`, `Clients/`, `Resources/`. +- **`./install.sh`** one-command install — vault skeleton + 5 hooks + GBrain (clone + ZE-embedded init) + gbq wrapper + launchd jobs (nightly 04:00 + reflection 12:00/23:00) + Obsidian install + global `CLAUDE.md` merge. Non-destructive: never overwrites an existing vault or settings. +- **`./install.sh --with-gstack`** option — clones and sets up [garrytan/gstack](https://github.com/garrytan/gstack) alongside (23 AI specialists for Claude Code). +- **`./install.sh --company `** — team mode, joins a shared company brain as a 2nd federated GBrain source. +- **`./setup-company.sh`** — admin scaffolds the company brain (`~/Documents/BrainCo/`), git inits, prints push + member-join instructions. +- **5 hooks** in `engine/hooks/`: + - `correction-detector.py` (UserPromptSubmit) — captures corrections to `lessons.md` + - `session-logger.py` + `session-indexer.py` (Stop) — per-session logs + - `session-recap.py` (Stop) — structured journal entry per session (no LLM) + - `daily-reflection.py` (cron, called by launchd 12:00 + 23:00) — LLM summary of the day +- **`gbq`** universal safe wrapper around `gbrain` — force-kill workaround on PGLite reads (`query/search/ask/graph-query`), clean `wait` on writes (`sync/embed/dream/skillify/brainstorm/code-def/code-refs/sources/...`). +- **Nightly maintenance** (`engine/nightly/gbrain-nightly.sh`) — stale-lock recovery → self-update gbrain → self-update gstack (if installed) → commit vault → sync personal + company → dream cycle. +- **`test-hooks.sh`** — verifies all 5 hooks (11 checks) + validates YAML frontmatters in `vault-skeleton/*/_template.md` (4 checks), in an isolated temp HOME. 15/15 expected. +- **CI** (`.github/workflows/test.yml`) — runs `test-hooks.sh` + shell syntax lint on every PR + push to master. +- **OSS hygiene** — MIT LICENSE, CONTRIBUTING.md, SECURITY.md, issue templates. + +### Security +- Repository history scrubbed of all personal/business identifiers before going public (multi-layer scan: file content + full git log + tier-1 contact names). +- Branch protection on `master` (1 PR review required, no force-push, no deletion). +- `~/.gbrain/config.json` written with mode 0600 (the ZeroEntropy API key never leaves the machine). +- Hooks resolve absolute paths at install time (sed `__HOME__` → `$HOME`) — no runtime path injection surface. + +### Known limitations +- macOS only (launchd for cron). Linux port welcome (issue first). +- Embeddings via ZeroEntropy (free tier). Ollama-local variant planned, not yet shipped. +- Auto-skill suggestion from session patterns is intentionally NOT shipped — speculative without real usage data. Will revisit after 2+ weeks of community usage. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b633041 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,60 @@ +# Contributing to brain-in-a-box + +Thanks for wanting to make this better. The project is small, the workflow is straightforward. + +## Quick rules + +- **macOS only** (the nightly + reflection rely on `launchd`). Linux/Windows ports welcome via discussion first — propose the approach before coding. +- **One concern per PR.** Schema change in one PR, doc change in another. Easier to review, easier to revert. +- **No secrets, ever.** Not in the vault, not in tests, not in code. The `file-protection.sh` hook tries to catch them but don't rely on it. +- **Match the existing style.** Concise English, no corporate fluff. Read what's there before writing. + +## Workflow + +The `master` branch is protected: no direct push, no force-push, no deletion. Every change goes through a PR. + +```bash +# 1. Branch from master +git checkout master && git pull --ff-only +git checkout -b / # e.g. fix/yaml-validation, feat/ollama-variant + +# 2. Make your change + +# 3. Run tests locally BEFORE pushing +bash test-hooks.sh # 15/15 expected (5 hooks + 4 YAML frontmatters) +bash -n install.sh # syntax check on every shell script you touched + +# 4. Push + open PR +git push -u origin +gh pr create # or use the GitHub UI + +# 5. CI runs automatically (.github/workflows/test.yml — macos-latest) +# All checks must pass. 1 review approval required before merge. +``` + +## What you can contribute + +- **Hook fixes** (`engine/hooks/*.py`) — fixes welcome, ping if behavior change +- **New skills** (`vault-skeleton/Skills/` templates) — gstack-compatible SKILL.md format +- **Docs** (`README.md`, `CONTRIBUTING.md`, this one) — clarity > completeness +- **CI improvements** (`.github/workflows/`) — make tests faster, add coverage +- **Linux port** (open an issue first to discuss approach — launchd needs replacement) +- **Ollama variant** (`engine/bin/gbq`, install.sh) — opt-in offline embeddings +- **Translations** (vault-skeleton templates) — keep the structure, swap the prose + +## What NOT to contribute + +- New folders in `vault-skeleton/` without strong rationale (the schema is meant to stay stable) +- Heavy dependencies (the install is bash + python3 + bun + git; keep it light) +- Telemetry, analytics, or any phone-home (the project is 100% local by design) + +## Where to ask first + +- **Vision / scope questions** → open a Discussion (not an Issue) +- **Bugs** → open an Issue using the template +- **Security vulnerabilities** → see [SECURITY.md](SECURITY.md), never an Issue +- **"Is this aligned with the roadmap?"** → ping in a Discussion before coding + +## A note on the maintainer's bandwidth + +This is a side project of one person. PRs that are tight, tested, and aligned get merged fast. PRs that need a lot of back-and-forth may sit. If your PR has been quiet for >2 weeks, ping it. diff --git a/README.md b/README.md index 6fdb511..275ddbe 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,10 @@ Each member's nightly pulls the team's contributions + re-indexes. The dream cyc ## Security / privacy - Everything is **local**: your vault, your index, your key. Nothing goes to a third party (except the text embedding sent to ZeroEntropy at indexing time — see their policy). - Never a secret in the vault (the `file-protection` hook + the directives remind you). +- **Found a security issue?** See [SECURITY.md](SECURITY.md) — please use GitHub Security Advisories, not public Issues. + +## Contributing +PRs welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow (the `master` branch is protected — every change goes through a PR). MIT licensed (see [LICENSE](LICENSE)). Changelog tracked in [CHANGELOG.md](CHANGELOG.md). ## Updating ```bash diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..1a7818f --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,54 @@ +# Security policy + +## Reporting a vulnerability + +**Do NOT open a public GitHub Issue for security bugs.** + +Use one of these instead: +1. **GitHub Security Advisories** (preferred): https://github.com/BrainInBox/brain-in-a-box/security/advisories/new +2. **Direct contact** via the maintainer's profile: https://github.com/Chad-Mufasax + +Include in the report: +- Steps to reproduce +- Impact (what an attacker could do) +- Suggested mitigation if you have one +- Whether you'd like credit in the fix announcement + +## Response + +The maintainer is one person. Reasonable response targets: +- **Acknowledgment**: within 72h +- **Triage + severity**: within 1 week +- **Fix or mitigation**: depends on severity (critical = days, low = weeks) + +## What's in scope + +- The `install.sh` script (running it on a clean Mac shouldn't be exploitable) +- The hooks (`engine/hooks/*.py`) — they execute on every Claude Code session +- The nightly script (`engine/nightly/gbrain-nightly.sh`) — runs as launchd +- The `gbq` wrapper — runs against your local gbrain +- Path-traversal / injection in any of the above + +## What's NOT in scope (upstream projects) + +- **GBrain** (garrytan/gbrain) — report to the gbrain project directly +- **gstack** (garrytan/gstack) — report to gstack project +- **ZeroEntropy** (the embedding API) — report to zeroentropy.dev +- **Claude Code** itself — report to Anthropic + +## What's NOT a vulnerability + +- A friend you added as collaborator can push code (that's collaboration, not a vuln — see the README discussion on trust models) +- The brain content is readable to whoever has access to your machine (it's plaintext markdown, by design) +- An attacker with shell access on your machine can read `~/.gbrain/config.json` (file is `0600`, but root or your own user can still read it — that's local-trust scope) + +## Hardening recommendations (for users) + +- Enable FileVault on your Mac (encrypts the vault at rest) +- Don't share your `~/Documents/Brain` over insecure channels +- If you set up team mode (BrainCo), use a private GitHub repo and audit who has access +- Never put secrets in the vault — references only (Keychain entries, file paths, env var names) + +## Credit + +Vulnerability reporters who follow this policy get credit in the fix release notes, unless they opt out.