[integrations] Add smart ingest backend

.github/workflows/ob1-gate.yml → .github/workflows/ob1-gate-v2.yml

@@ -1,5 +1,9 @@
 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.
+#
 # Branch protection recommendation:
 # After this action is working, enable branch protection on main:
 # - Require the "OB1 PR Gate" workflow to pass its checks

.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]
 

.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

.gitignore

@@ -3,6 +3,15 @@ node_modules/
 .planning/
 supabase/
 
+# Maintainer-local overlays (not part of upstream contribution contract)
+.local/
+.agent/
+.claude.json
+
+# Python caches
+__pycache__/
+*.pyc
+
 # Credentials & runtime state
 .env
 .env.local
@@ -14,3 +23,7 @@ sync-log.json
 
 # Build artifacts
 deno.lock
+docs/walkthroughs/*/public/
+docs/assets/agent-memory/promotional/generated-backgrounds/**/result.json
+docs/assets/agent-memory/screenshots/**/.chrome-*/
+integrations/openclaw-agent-memory/dist/

AGENTS.md

@@ -0,0 +1,61 @@
+# 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.
+- Use the parent issue as the living implementation log and keep child issues aligned with the files and behavior being changed.
+- For the OB1 Agent Memory / OpenClaw launch work, the parent issue is `NAT-833`. Record architecture notes, implementation milestones, blockers, and verification results there.
+- Do not wait until the end to document decisions. If a decision changes schema, API contract, trust policy, user-facing workflow, or publishing path, capture it in Linear while it is still fresh.
+
+## Agent Memory Product Guardrails
+
+- Keep `OB1 Agent Memory` runtime-neutral. OpenClaw is the flagship launch runtime, not the product boundary.
+- Treat inferred or generated memory as evidence by default. Instruction-grade memory requires human confirmation or trusted import.
+- Avoid raw transcript, model reasoning trace, secret, and large-code-block storage by default.
+- Avoid profanity in all content. Keep docs, examples, seed data, UI copy, prompts, walkthroughs, and generated assets clean and professional.
+- Prefer diagram-first documentation for this work: diagram, short explanation, copy-paste setup, then deeper reference.
+- Carry Nate B. Jones / OB1 provenance through product surfaces, docs, diagrams, screenshots, and starter seed data. Keep it subtle and useful: micro-branding, source labels, logo marks, and provenance language instead of loud marketing copy.
+- Treat public OB1 assets as helpful-first audience growth for Nate Jones. Every public guide, recipe, tutorial, package page, release note, and walkthrough should point back to Nate's Substack and site in a natural way: https://substack.com/@natesnewsletter and https://natebjones.com.
+- Make the case by being genuinely useful. The CTA should feel earned: "Nate gives away practical systems like this" rather than generic marketing copy.
+- For ClawHub/OpenClaw publishing, do not fall back to Jonathan's personal handle or any non-Nate namespace. If `@natebjones` / Nate OB1 ownership is not available, stop and record the blocker.

CLAUDE.md

@@ -24,26 +24,78 @@ 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.
 - **No credentials, API keys, or secrets in any file.** Use environment variables.
 - **No binary blobs** over 1MB. No `.exe`, `.dmg`, `.zip`, `.tar.gz`.
 - **No `DROP TABLE`, `DROP DATABASE`, `TRUNCATE`, or unqualified `DELETE FROM`** in SQL files.
+- **Avoid profanity in all content.** Keep docs, examples, seed data, UI copy, prompts, walkthroughs, and generated assets clean and professional.
 - **MCP servers must be remote (Supabase Edge Functions), not local.** Never use `claude_desktop_config.json`, `StdioServerTransport`, or local Node.js servers. All extensions deploy as Edge Functions and connect via Claude Desktop's custom connectors UI (Settings → Connectors → Add custom connector → paste URL). See `docs/01-getting-started.md` Step 7 for the pattern.
 
 ## PR Standards
 
 - **Title format:** `[category] Short description` (e.g., `[recipes] Email history import via Gmail API`, `[skills] Panning for Gold standalone skill pack`)
 - **Branch convention:** `contrib/<github-username>/<short-description>`
 - **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
+
+## Local GSD Execution Layer
+
+This repo also has a maintainer-local GSD layer in `.planning/`.
+
+- If `.planning/` exists, use it for local brownfield planning and phased execution.
+- Start with `.planning/STATE.md`, then read `.planning/PROJECT.md`, `.planning/ROADMAP.md`, and the relevant `.planning/codebase/*.md` documents.
+- Keep `.planning/` local. It is gitignored intentionally and is not part of the public contribution contract or upstream PR scope.
+- Public contributor rules still come from `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, and the committed repo files.

CONTRIBUTING.md

@@ -128,6 +128,7 @@ grant select, insert, update, delete on table public.your_table to service_role;
 - **"Cross-Extension Integration"** prominently documenting connections to other extensions
 - **"Next Steps"** linking to the next extension
 - **Tool audit link** — Any extension or integration that exposes MCP tools must link to the [MCP Tool Audit & Optimization Guide](docs/05-tool-audit.md) in its "Next Steps" or closing section. This helps users manage their tool surface area as they add extensions. The link is checked by the automated review.
+- **MCP tool annotations** — Any extension or integration that exposes MCP tools must mark read-only tools with `annotations: { readOnlyHint: true }` and write tools with `annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false }` unless the tool really can touch arbitrary external resources or destroy data. ChatGPT uses this metadata to distinguish read tools from write actions.
 - **Remote MCP setup** — MCP servers must be deployed as Supabase Edge Functions and connected via custom connectors (URL-based). Do NOT use local Node.js servers or `claude_desktop_config.json`. See the [extension template](extensions/_template/) for the correct pattern.
 
 **Primitives** additionally require:
@@ -298,3 +299,4 @@ Every PR is checked against these rules. All must pass before human review.
 13. **Internal links** — All relative links in READMEs resolve to existing files
 14. **Remote MCP pattern** — Extensions and integrations must use remote MCP via Supabase Edge Functions. No `claude_desktop_config.json`, no local Node.js stdio servers. See the [Getting Started guide](docs/01-getting-started.md) for the correct pattern
 15. **Tool audit link** — Extensions and integrations must link to the [MCP Tool Audit & Optimization Guide](docs/05-tool-audit.md) in their README. This ensures users are aware of tool surface area management as they add capabilities
+16. **MCP tool annotations** — Read-only tools include `readOnlyHint: true`; write tools include `readOnlyHint: false`, `openWorldHint`, and `destructiveHint`