diff --git a/.github/workflows/ob1-gate.yml b/.github/workflows/ob1-gate-v2.yml similarity index 98% rename from .github/workflows/ob1-gate.yml rename to .github/workflows/ob1-gate-v2.yml index fdf56e9be..de229228a 100644 --- a/.github/workflows/ob1-gate.yml +++ b/.github/workflows/ob1-gate-v2.yml @@ -1,5 +1,11 @@ name: OB1 PR Gate +# This workflow used to live at `.github/workflows/ob1-gate.yml`. +# It was renamed to force GitHub Actions to register a fresh workflow after +# the old workflow id began creating runs with zero jobs. +# This copy carries the Humestone hardening (env-passed untrusted values, +# fail-closed diffs, title-bypass fix) applied to the pre-rename file. +# # ── Branch protection setup (admin-only, one-time) ────────────── # 1. Settings → Branches → Add branch protection rule for "main" # 2. Check "Require status checks to pass before merging" diff --git a/.github/workflows/ob1-pr-followups.yml b/.github/workflows/ob1-pr-followups.yml index af3a225d2..e22180dc2 100644 --- a/.github/workflows/ob1-pr-followups.yml +++ b/.github/workflows/ob1-pr-followups.yml @@ -4,6 +4,7 @@ on: workflow_run: workflows: - "OB1 PR Gate" + - ".github/workflows/ob1-gate-v2.yml" - ".github/workflows/ob1-gate.yml" types: [completed] diff --git a/.github/workflows/update-readme-contributions.yml b/.github/workflows/update-readme-contributions.yml new file mode 100644 index 000000000..636b80126 --- /dev/null +++ b/.github/workflows/update-readme-contributions.yml @@ -0,0 +1,38 @@ +name: Update README Contributions + +on: + workflow_dispatch: + schedule: + - cron: "17 9 * * *" + +permissions: + contents: write + pull-requests: write + +jobs: + update: + runs-on: ubuntu-latest + steps: + - name: Checkout main + uses: actions/checkout@v4 + with: + ref: main + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Update README recent contributions + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: node scripts/update-readme-contributions.mjs + + - name: Open README update PR + uses: peter-evans/create-pull-request@v6 + with: + commit-message: "[docs] Refresh README recent contributions" + title: "[docs] Refresh README recent contributions" + body: "Automated refresh of the generated Recent Contributions section in README.md." + branch: automation/readme-recent-contributions + delete-branch: true diff --git a/AGENTS.md b/AGENTS.md index e30862632..4b1f6851a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,46 @@ # OB1 Agent Instructions +## Parallel Agent Worktrees + +When multiple AI agents or assistant chats work on this repo, do not put them in the same checkout. + +### Setup pattern + +- Treat the main repo checkout as the canonical repo for pulling, inspection, and creating worktrees. +- Create one Git worktree per active agent, task, or PR-sized workstream. +- Give each worktree a descriptive folder name and a matching branch name. +- Start every agent task by naming the exact absolute worktree path it owns. +- The assigned worktree path is the boundary. The chat is not the boundary. + +### Agent assignment template + +Start each parallel-agent task with: + +```text +Repository worktree: +/ABSOLUTE/PATH/TO/PROJECT-WORKTREE + +Branch: +codex/SHORT-TASK-NAME + +Task: +DESCRIBE THE EXACT WORK. +``` + +### Rules + +- Do not switch branches in the canonical repo while another agent may be working. +- Do not edit sibling worktrees unless explicitly asked. +- Before staging or committing, run `git status --short` and stage only files that belong to the current task. +- If `main` or another branch changed underneath the worktree, pause before merging or rebasing unless the task explicitly says to finish the PR end to end. +- After a branch is merged and the worktree is clean, remove the finished worktree with `git worktree remove /ABSOLUTE/PATH/TO/PROJECT-WORKTREE`. + +### Quick checks + +- If another chat suddenly changed branches, both chats were probably in the same working directory. +- If `git worktree add` says a branch is already checked out, create a new branch name or remove the old clean worktree. +- If cleanup fails, inspect `git status --short` and preserve uncommitted work. + ## Required Step: Update Linear - For feature work tied to a Linear issue, update Linear at the start of the work, at meaningful checkpoints, and before handing back to the user. diff --git a/CLAUDE.md b/CLAUDE.md index 08513493c..a86a68d6b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,6 +24,47 @@ resources/ — Official companion files and packaged exports. Every contribution lives in its own subfolder under the right category and must include `README.md` + `metadata.json`. +## Parallel Agent Worktrees + +When multiple AI agents or assistant chats work on this repo, do not put them in the same checkout. + +### Setup pattern + +- Treat the main repo checkout as the canonical repo for pulling, inspection, and creating worktrees. +- Create one Git worktree per active agent, task, or PR-sized workstream. +- Give each worktree a descriptive folder name and a matching branch name. +- Start every agent task by naming the exact absolute worktree path it owns. +- The assigned worktree path is the boundary. The chat is not the boundary. + +### Agent assignment template + +Start each parallel-agent task with: + +```text +Repository worktree: +/ABSOLUTE/PATH/TO/PROJECT-WORKTREE + +Branch: +codex/SHORT-TASK-NAME + +Task: +DESCRIBE THE EXACT WORK. +``` + +### Rules + +- Do not switch branches in the canonical repo while another agent may be working. +- Do not edit sibling worktrees unless explicitly asked. +- Before staging or committing, run `git status --short` and stage only files that belong to the current task. +- If `main` or another branch changed underneath the worktree, pause before merging or rebasing unless the task explicitly says to finish the PR end to end. +- After a branch is merged and the worktree is clean, remove the finished worktree with `git worktree remove /ABSOLUTE/PATH/TO/PROJECT-WORKTREE`. + +### Quick checks + +- If another chat suddenly changed branches, both chats were probably in the same working directory. +- If `git worktree add` says a branch is already checked out, create a new branch name or remove the old clean worktree. +- If cleanup fails, inspect `git status --short` and preserve uncommitted work. + ## Guard Rails - **Never modify the core `thoughts` table structure.** Adding columns is fine; altering or dropping existing ones is not. @@ -38,13 +79,14 @@ Every contribution lives in its own subfolder under the right category and must - **Title format:** `[category] Short description` (e.g., `[recipes] Email history import via Gmail API`, `[skills] Panning for Gold standalone skill pack`) - **Branch convention:** `contrib//` - **Commit prefixes:** `[category]` matching the contribution type -- Every PR must pass the automated review checks in `.github/workflows/ob1-review.yml` before human review +- Every PR must pass the automated review checks in `.github/workflows/ob1-gate-v2.yml` before human review - See `CONTRIBUTING.md` for the full review process, metadata.json template, and README requirements ## Key Files - `CONTRIBUTING.md` — Source of truth for contribution rules, metadata format, and the review process -- `.github/workflows/ob1-review.yml` — Automated PR review +- `.github/workflows/ob1-gate-v2.yml` — Automated PR gate +- `.github/workflows/claude-review.yml` — Maintainer-triggered Claude PR review - `.github/metadata.schema.json` — JSON schema for metadata.json validation - `.github/PULL_REQUEST_TEMPLATE.md` — PR description template - `LICENSE.md` — FSL-1.1-MIT terms diff --git a/README.md b/README.md index ebca0d5c6..b756ff742 100644 --- a/README.md +++ b/README.md @@ -10,12 +10,8 @@ This isn't a notes app. It's a database with vector search and an open protocol > Open Brain was created by [Nate B. Jones](https://natesnewsletter.substack.com/). Follow the [Substack](https://natesnewsletter.substack.com/) for updates, discussion, and the companion prompt pack. Join the [Discord](https://discord.gg/Cgh9WJEkeG) for real-time help and community. -https://github.com/user-attachments/assets/80a79b09-f323-42c6-b11b-de10bb6fa36f - ## Getting Started -https://github.com/user-attachments/assets/85208d73-112b-4204-82fd-d03b6c397a8b - Never built an Open Brain? Start here: 1. **[Setup Guide](docs/01-getting-started.md)** — Build the full system (database, AI gateway, Slack capture, MCP server) in about 45 minutes. No coding experience needed. Or watch the [video walkthrough](https://vimeo.com/1174979042/f883f6489a) (~27 min). @@ -25,9 +21,38 @@ Never built an Open Brain? Start here: **If you hit a wall:** We built a [FAQ](docs/03-faq.md) that covers the most common questions and gotchas. And if you need real-time help, we created dedicated AI assistants that know this system inside and out: a [Claude Skill](https://www.notion.so/product-templates/Open-Brain-Companion-Claude-Skill-31a5a2ccb526802797caeb37df3ba3cb?source=copy_link), a [ChatGPT Custom GPT](https://chatgpt.com/g/g-69a892b6a7708191b00e48ff655d5597-nate-jones-open-brain-assistant), and a [Gemini GEM](https://gemini.google.com/gem/1fDsAENjhdku-3RufY7ystbS1Md8MtDCg?usp=sharing). Use whichever one matches the AI tool you already use. -## Extensions — The Learning Path +## Recent Contributions + +The 20 most recent merged PRs. This list is generated from GitHub and refreshes daily. Last updated: 2026-05-22. + + + +| Contribution | What changed | Creator | +| ------------ | ------------ | ------- | +| [Provenance chains — derivation tracking](recipes/provenance-chains/) | Provenance chains — derivation tracking. | [@alanshurafa](https://github.com/alanshurafa) | +| [Open Brain Dashboard Pro — Next.js 16 + iron-session](dashboards/open-brain-dashboard-pro/) | Open Brain Dashboard Pro — Next.js 16 + iron-session. | [@alanshurafa](https://github.com/alanshurafa) | +| [Atomizer — generic + Gmail re-atomization toolkit](recipes/atomizer/) | Atomizer — generic + Gmail re-atomization toolkit. | [@alanshurafa](https://github.com/alanshurafa) | +| [Brain smoke test — install verification harness](recipes/brain-smoke-test/) | Brain smoke test — install verification harness. | [@alanshurafa](https://github.com/alanshurafa) | +| [CRM improvements: crm_ prefix, FTS search, meeting prep, stale detection](extensions/professional-crm/) | CRM improvements: crm_ prefix, FTS search, meeting prep, stale detection. | [@pintomatic](https://github.com/pintomatic) | +| [Edge function cost optimization — 73% invocation reduction](recipes/edge-function-cost-optimization/) | Edge function cost optimization — 73% invocation reduction. | [@JustinTSmith](https://github.com/JustinTSmith) | +| [Obsidian-vault-import: --source-label to override metadata.source](recipes/obsidian-vault-import/) | Obsidian-vault-import: --source-label to override metadata.source. | [@dhanjit](https://github.com/dhanjit) | +| [Preserve full frontmatter in obsidian-vault-import metadata](recipes/obsidian-vault-import/) | Preserves full frontmatter in obsidian-vault-import metadata. | [@dhanjit](https://github.com/dhanjit) | +| [Load .env into wiki-compiler child processes](recipes/wiki-compiler/) | Loads .env into wiki-compiler child processes. | [@mlava](https://github.com/mlava) | +| [Enable standalone output for Docker builds](dashboards/open-brain-dashboard-next/) | Enables standalone output for Docker builds. | [@Mavrick-F](https://github.com/Mavrick-F) | +| [Fix outdated primitives section in README](README.md) | Fixes outdated primitives section in README. | [@jjshanks](https://github.com/jjshanks) | +| [Document Edge Function redeploy step in OpenRouter rotation FAQ](docs/03-faq.md) | Documents Edge Function redeploy step in OpenRouter rotation FAQ. | [@Silverhawk-bit](https://github.com/Silverhawk-bit) | +| [Return JSON-RPC error envelopes on auth failure](server/index.ts) | Returns JSON-RPC error envelopes on auth failure. | [@txcfi-scott](https://github.com/txcfi-scott) | +| [Markdownlint sweep for existing recipe/schema docs](schemas/workflow-status/) | Markdownlint sweep for existing recipe/schema docs. | [@alanshurafa](https://github.com/alanshurafa) | +| [Improve ChatGPT MCP compatibility](primitives/remote-mcp/) | Improves ChatGPT MCP compatibility. | [@justfinethanku](https://github.com/justfinethanku) | +| [Add wiki compiler orchestration recipe](recipes/wiki-compiler/) | Adds wiki compiler orchestration recipe. | [@justfinethanku](https://github.com/justfinethanku) | +| [Wiki synthesis + autobiography pipeline](recipes/wiki-synthesis/) | Wiki synthesis + autobiography pipeline. | [@alanshurafa](https://github.com/alanshurafa) | +| [Entity wiki pages from knowledge graph](recipes/entity-wiki/) | Entity wiki pages from knowledge graph. | [@alanshurafa](https://github.com/alanshurafa) | +| [Typed reasoning edges + Opus/Haiku classifier](schemas/typed-reasoning-edges/) | Typed reasoning edges + Opus/Haiku classifier. | [@alanshurafa](https://github.com/alanshurafa) | +| [Entity extraction worker](integrations/entity-extraction-worker/) | Entity extraction worker. | [@alanshurafa](https://github.com/alanshurafa) | + + -https://github.com/user-attachments/assets/cc477f00-bb6b-4f96-9f7d-a6bcd0cf8b60 +## Extensions — The Learning Path Build these in order. Each one teaches new concepts through something you'll actually use. By the end, your agent manages your household, your schedule, your meals, your professional network, and your career — all interconnected. @@ -44,19 +69,18 @@ Extensions compound. Your CRM knows about thoughts you've captured. Your meal pl ## Primitives: Concepts That Compound -https://github.com/user-attachments/assets/f488e495-fe2a-4ccc-a834-fc6ab5a0ed41 - Some concepts show up in multiple extensions. Learn them once, apply them everywhere. | Primitive | What It Teaches | Used By | | --------- | --------------- | ------- | +| [Deploy an Edge Function](primitives/deploy-edge-function/) | Deploying any extension as a Supabase Edge Function | All extensions | +| [Remote MCP Connection](primitives/remote-mcp/) | Connecting to Claude Desktop, ChatGPT, Claude Code, Cursor, and other clients | All extensions | +| [Common Troubleshooting](primitives/troubleshooting/) | Solutions for connection, deployment, and database issues | All extensions | | [Row Level Security](primitives/rls/) | PostgreSQL policies for multi-user data isolation | Extensions 4, 5, 6 | | [Shared MCP Server](primitives/shared-mcp/) | Giving others scoped access to parts of your brain | Extension 4 | ## Community Contributions -https://github.com/user-attachments/assets/9454662f-2648-4928-8723-f7d52e94e9b8 - Beyond the curated learning path, the community builds and shares real tools that real people use. Every contribution below was reviewed, approved, and merged by the maintainer team. Look for the **Community Contribution** badge in each README. ### [`/recipes`](recipes/) — Import Your Data @@ -145,12 +169,6 @@ Tables and sidecars that extend the base `thoughts` model without replacing it. | ------ | ------------ | ----------- | | [Agent Memory](schemas/agent-memory/) | Provenance, review, use-policy, source-reference, relation, recall-trace, and audit sidecars for agent workflow memory | OB1 Team | -### [`/primitives`](primitives/) — Reusable Patterns - -| Primitive | What It Does | Contributor | -| --------- | ------------ | ----------- | -| [Content Fingerprint Dedup](primitives/content-fingerprint-dedup/) | SHA-256 deduplication for thought ingestion — prevents duplicates across all import recipes | [@alanshurafa](https://github.com/alanshurafa) | - ## Using a Contribution 1. Browse the category tables above or the folders in the repo @@ -166,7 +184,7 @@ Read [CONTRIBUTING.md](CONTRIBUTING.md) for the full details. The short version: - **Primitives** should be referenced by 2+ extensions to justify extraction - **Recipes, schemas, dashboards, integrations, and skills** are open for community contributions - Every PR runs through an automated review agent that checks structure, secrets, SQL safety, dependencies, and documentation quality -- If the agent passes, a human admin reviews for quality and clarity +- If the agent passes, a human maintainer reviews for quality and clarity - Your contribution needs a README with real instructions and a `metadata.json` with structured info ## Community @@ -176,7 +194,9 @@ Read [CONTRIBUTING.md](CONTRIBUTING.md) for the full details. The short version: ## Who Maintains This -Built by Nate B. Jones's team. Matt Hallett is the first community admin and repo manager. PRs are reviewed by the automated agent + human admins. +Created by [Nate B. Jones](https://github.com/NateBJones). + +The OB1 repo team: [Jonathan Edwards](https://github.com/justfinethanku), Repo Manager; [Matt Hallett](https://github.com/matthallett1), Community Admin; [Alan Shurafa](https://github.com/alanshurafa), Community Maintainer. PRs are reviewed by the automated agent + human maintainers. ## License diff --git a/dashboards/ob1-canonical-landing/404.html b/dashboards/ob1-canonical-landing/404.html new file mode 100644 index 000000000..3d605d34e --- /dev/null +++ b/dashboards/ob1-canonical-landing/404.html @@ -0,0 +1,68 @@ + + + + + + Page not found — Open Brain + + + + + + + + +
+ +
+
404
+

Page not found

+

This page doesn’t exist. The brain has no memory of it.

+ Return home → + + diff --git a/dashboards/ob1-canonical-landing/CNAME b/dashboards/ob1-canonical-landing/CNAME new file mode 100644 index 000000000..a72a42c87 --- /dev/null +++ b/dashboards/ob1-canonical-landing/CNAME @@ -0,0 +1 @@ +openbrain.fyi \ No newline at end of file diff --git a/dashboards/ob1-canonical-landing/MAINTENANCE.md b/dashboards/ob1-canonical-landing/MAINTENANCE.md new file mode 100644 index 000000000..231e98f6d --- /dev/null +++ b/dashboards/ob1-canonical-landing/MAINTENANCE.md @@ -0,0 +1,222 @@ +# Maintaining openbrain.fyi + +This guide is for the OB1 maintainer and any future contributors who need to update the canonical landing page after it goes live. The page is intentionally a single static `index.html` with no build step — every change is a normal git edit, and every deploy is a single push. + +## Edit-and-deploy loop + +1. Edit any file under `dashboards/ob1-canonical-landing/` +2. Open a PR (or push to `main` if you have direct write access) +3. The `Deploy landing page` workflow fires on the path filter and pushes the artifact to Pages +4. The `https://openbrain.fyi/` cache refreshes within 1–2 minutes of the deploy job finishing + +Watch progress at **Actions → Deploy landing page**. The job's environment URL links to the live site once it's published. + +## Common edits + +### Update copy, headlines, or links + +All visible text lives directly in `index.html`. The major sections are marked with HTML `id`s for navigation: + +| `id` | Section | +|------|---------| +| `main-content` | Skip-link target, wraps everything below the nav | +| (hero, no id) | The first `
` — h1, byline, CTA buttons, demo video | +| `how-it-works` | Three-pillar overview | +| `get-started` | Numbered steps + AI-assistant cards + companion prompts | +| `extensions` | Extensions table | +| `community` | Recipes + tools + skills tables, dashboards/integrations pillars | + +After any copy change, update `dateModified` in three places so search engines and citations stay in sync: + +| File | Field | +|------|-------| +| `index.html` | `` | +| `index.html` | JSON-LD `TechArticle` → `"dateModified"` | +| `index.html` | Byline `` | +| `sitemap.xml` | `` | +| `metadata.json` | `"updated"` | + +All five should be the same ISO date (`YYYY-MM-DD`). + +### Add or swap a video + +Videos use GitHub user-attachment URLs (the same URLs that render in the project README). To add a new video: + +1. Drag the `.mp4` into a GitHub issue or PR comment to upload it; copy the `https://github.com/user-attachments/assets/...` URL +2. Embed using the existing pattern: + +```html + +``` + +Always set a meaningful `aria-label` — screen readers announce it. Use `preload="metadata"` only for the hero video; keep all below-fold videos at `preload="none"` to protect first-paint performance. + +If a GitHub user-attachment URL ever goes 404, replace with a re-uploaded asset; do not host video binaries in the repo (gate rule blocks files >1MB). + +### Replace or update the logo + +The page ships three brand-image variants generated from a single source: + +| File | Use | Source | +|------|-----|--------| +| `imgs/ob1-logo.png` (512×512) | Nav + manifest icon | Square master | +| `imgs/ob1-logo-wide.png` (1200×360) | Hero banner | Wide master | +| `imgs/og.png` (1200×630) | Social share | Wide on `#0f1b33` background | +| `imgs/apple-touch-icon.png` (180×180) | iOS home screen | Square master | +| `imgs/favicon-32.png` (32×32) | Browser tab | Square master | + +To regenerate from new master images, drop the new sources at `imgs/_master-square.png` and `imgs/_master-wide.png`, then run: + +```bash +cd dashboards/ob1-canonical-landing/imgs +magick _master-square.png -resize 512x512 -strip ob1-logo.png +magick _master-square.png -resize 180x180 -strip apple-touch-icon.png +magick _master-square.png -resize 32x32 -strip favicon-32.png +magick _master-wide.png -resize 1200x -strip ob1-logo-wide.png +magick _master-wide.png -resize 1000x -background "#0f1b33" -gravity center -extent 1200x630 og.png +rm _master-square.png _master-wide.png +``` + +Requires ImageMagick 7+ (`brew install imagemagick`). The `-strip` flag removes EXIF/color-profile metadata that bloats files and leaks build-environment info. + +If the logo's color palette changes, update the four CSS custom properties in the `:root` block of `index.html`: + +```css +--accent: #e05a20; /* primary accent (OB1 orange) */ +--brand-blue-deep: #0f1b33; /* used in hero gradient + OG bg */ +--brand-blue-mid: #1a3a6e; +--brand-blue-bright: #2563b8; +``` + +### Add a new content section + +Use the existing pattern so styling, spacing, and a11y stay consistent: + +```html +
+
+

Section title

+

Lead paragraph.

+ +
+
+``` + +Alternate `
` and `
` for visual rhythm. Add a nav link in the sticky `