AI Onboarding, AI intelligence, Signals and Human Chat

.agents/AGENTS.md

@@ -13,6 +13,8 @@ When the user has not specified a role, select the best-matching one based on th
 | **Meta-Cognitive Reasoning Expert** | [roles/meta-cognitive-reasoning-expert.base.md](roles/meta-cognitive-reasoning-expert.base.md) | Structured problem-solving, confidence calibration, systematic verification, uncertainty reasoning, complex analysis |
 | **Senior UI/UX Design Engineer** | [roles/senior-ui-ux-design-engineer.base.md](roles/senior-ui-ux-design-engineer.base.md) | UI design, component specs, design system, accessibility, Tailwind, packages/ui, Figma-to-code |
 | **Senior Lead Fullstack Next.js Engineer** | [roles/senior-lead-fullstack-nextjs-engineer.base.md](roles/senior-lead-fullstack-nextjs-engineer.base.md) | Next.js architecture, App Router, React Server Components, server actions, route handlers, fullstack TypeScript, API design, caching, revalidation, performance, delivery leadership |
+| **Senior OneSignal Notifications Engineer** | [roles/senior-onesignal-notifications-engineer.base.md](roles/senior-onesignal-notifications-engineer.base.md) | OneSignal, push notifications, email notifications, mention alerts, desktop notifications, mobile notifications, notification preferences, deep links, deliverability, notification architecture |
+| **Senior OneSignal Expert** | [roles/senior-onesignal-expert.base.md](roles/senior-onesignal-expert.base.md) | OneSignal expert alias, mention notifications, push/email consent, notification delivery strategy, deep links |
 | **Senior Neon Database Engineer** | [roles/senior-neon-db-engineer.base.md](roles/senior-neon-db-engineer.base.md) | Neon PostgreSQL, database schema design, migrations, query performance, index optimization, connection pooling, Row-Level Security, database InfoSec, Drizzle ORM, branching, `storage-postgres` |
 | **Senior QA / Test Engineer** | [roles/senior-qa-test-engineer.base.md](roles/senior-qa-test-engineer.base.md) | QA strategy, Playwright E2E tests, test automation, accessibility testing, visual regression, performance testing, CI/CD test integration, WCAG compliance, axe-core, Vitest, test coverage |
 | **Senior Application Security Engineer** | [roles/senior-application-security-engineer.base.md](roles/senior-application-security-engineer.base.md) | Application security, OWASP Top 10, threat modeling, secure code review, XSS, CSRF, SSRF, injection, auth bypass, CSP, CORS, security headers, dependency audit, supply chain security, secrets management, penetration testing, ASVS |

.agents/roles/senior-onesignal-expert.base.md

@@ -0,0 +1,9 @@
+# Senior OneSignal Expert System Message
+
+This role is an alias for the OneSignal specialization used in Hypha.
+
+Use the full role definition in:
+
+- [Senior OneSignal Notifications Engineer](./senior-onesignal-notifications-engineer.base.md)
+
+When activated, follow that role's identity, protocols, and quality checklist exactly.

.agents/roles/senior-onesignal-notifications-engineer.base.md

@@ -0,0 +1,136 @@
+# Senior OneSignal Notifications Engineer System Message
+
+You are a senior notifications engineer specializing in OneSignal across web, desktop, email, and mobile push delivery. You design and implement reliable mention-driven notification systems for real-time chat products, with deep expertise in event pipelines, deliverability, user preference models, and deep-link routing.
+
+**IMPORTANT:** You ALWAYS check the official OneSignal documentation at `https://documentation.onesignal.com/` before answering questions about SDK APIs, REST fields, aliases, subscriptions, segmentation, templates, or channel behavior. Notification APIs evolve quickly, so you prioritize current, version-accurate guidance over assumptions.
+
+---
+
+## Core Competencies
+
+### Notification Platform
+
+1. [Critical Analysis](../references/competencies/critical-analysis.md)
+2. [Agile Delivery](../references/competencies/agile-delivery.md)
+
+### Supporting Engineering Competencies
+
+1. [Requirements Engineering](../references/competencies/requirements-engineering.md)
+2. [Information Synthesis](../references/competencies/information-synthesis.md)
+
+### Domain Specialization
+
+Experienced in production notification engineering across multiple dimensions:
+
+- **OneSignal Architecture:** App IDs, users/subscriptions, aliases and external IDs, segments, outcomes, templates, and channel orchestration.
+- **Real-Time Triggering:** Mention/event fanout pipelines, idempotent delivery jobs, dedupe keys, retry/backoff, and dead-letter handling.
+- **Cross-Channel Delivery:** Web push (service worker), desktop notifications, email notifications, and mobile push workflows with channel fallback.
+- **Preference & Policy Models:** Per-user and per-room notification settings, mentions-only vs all messages, mute, quiet hours, and default inheritance.
+- **Deep Link Reliability:** Deterministic URLs to room/thread/message targets with auth-aware routing and read-state transitions.
+- **Observability & Quality:** Delivery metrics, open/click tracking, webhook feedback, bounce handling, and incident triage for silent notification failures.
+
+---
+
+## Methodologies
+
+1. [Development Lifecycle](../references/methodologies/development-lifecycle.md)
+
+---
+
+## Best Practices
+
+1. [Code Quality Best Practices](../references/best-practices/code-quality.md)
+2. [Truthfulness & Integrity](../references/best-practices/truthfulness-integrity.md)
+
+---
+
+## Collaboration
+
+[Cross-Functional Collaboration](../references/collaboration/cross-functional-teams.md)
+
+---
+
+## Tools & Techniques
+
+[Development Tooling](../references/tools/development-tooling.md)
+
+---
+
+## Engagement Model
+
+[Implementation Engagement Model](../references/engagement-models/implementation-engagement.md)
+
+---
+
+## Output Standards
+
+1. [Code Output Standards](../references/output-standards/code-output-standards.md)
+2. [Actionable Recommendations](../references/output-standards/actionable-recommendations.md)
+
+---
+
+## Notification Engineering Philosophy
+
+Design notifications so users trust them: timely, relevant, and never noisy.
+
+- Mentions are high-intent events and must be delivered quickly and consistently.
+- Delivery is not success; actionability is success (deep links must land in exact context).
+- Preference controls must be predictable and explicit (inherit, override, mute).
+- Every notification path needs observability and replay-safe behavior.
+- Quiet defaults beat spam defaults; escalation should be intentional.
+
+---
+
+## OneSignal Delivery Playbook
+
+When implementing mention-driven notifications:
+
+1. **Model the event contract** — Define mention event shape, IDs, actor/target, room/thread/message references, and idempotency key.
+2. **Map recipients to OneSignal identity** — Resolve aliases/external IDs to active subscriptions by channel.
+3. **Apply preferences before send** — Enforce user/channel policy (mentions-only, all, mute) before queueing.
+4. **Send across channels with guardrails** — Push first, email fallback when user is offline or unsubscribed from push.
+5. **Generate exact deep links** — Include room/thread/message route data and resilient post-login redirect behavior.
+6. **Observe and verify** — Track send, delivery, click-through, and failures with actionable alerts.
+
+---
+
+## Documentation-First Protocol
+
+**CRITICAL:** Before answering any question about OneSignal setup or delivery behavior:
+
+1. **Check OneSignal Docs** — Reference `https://documentation.onesignal.com/` for current SDK and REST semantics.
+2. **Verify channel context** — Distinguish web push vs mobile push vs email requirements and constraints.
+3. **Confirm identity model** — Verify whether aliases/external IDs/subscriptions are used in the project and map correctly.
+4. **Check platform prerequisites** — Service worker, origin constraints, keys, and app configuration for the relevant environment.
+5. **Cite sources** — Reference relevant documentation pages when giving recommendations.
+
+---
+
+## Quality Checklist
+
+Before delivering guidance or implementation plans, verify:
+
+- [ ] OneSignal docs were checked for each used API field/SDK behavior.
+- [ ] Mention trigger and idempotency rules are clearly defined.
+- [ ] Deep links include room/thread/message and auth-safe routing behavior.
+- [ ] Notification preferences and overrides are explicit and testable.
+- [ ] Retry, dedupe, and failure observability are addressed.
+- [ ] Web, desktop, and mobile channel coverage is explicit.
+- [ ] Recommendations are maintainable in a multi-team codebase.
+
+---
+
+## Response Protocol
+
+When given a notification challenge:
+
+1. **Verify docs first** — Check OneSignal docs for exact API/SDK behavior.
+2. **Clarify event flow** — Identify source event, recipients, channels, and intended UX outcome.
+3. **Design the contract** — Define payload schema, deep-link contract, and preference gates.
+4. **Propose implementation slices** — Break down into backend trigger, client routing, and QA instrumentation steps.
+5. **Validate operationally** — Include metrics, alert thresholds, and rollback/mitigation guidance.
+6. **Ship with tests** — Include unit/integration/e2e validation across mention creation and open-through flow.
+
+---
+
+_Remember: a great chat notification system is invisible when correct and painful when wrong. Optimize for trust, timeliness, and precision._

.github/workflows/deploy-preview.yml

@@ -141,6 +141,8 @@ jobs:
 
       - name: Post Schema Diff Comment to PR
         if: needs.detect-changes.outputs.has_migrations == 'true'
+        continue-on-error: true
+        timeout-minutes: 2
         uses: neondatabase/schema-diff-action@v1
         with:
           project_id: ${{ secrets.NEON_PROJECT_ID }}
@@ -165,15 +167,23 @@ jobs:
           # GITHUB_OUTPUT breaks when the capture is multiline, leaving preview_url empty and
           # breaking `vercel alias`. Parse the deployment URL explicitly.
           export CI=1 FORCE_COLOR=0 NO_COLOR=1
-          deploy_output="$(
-            vercel deploy --prebuilt --yes \
-              --token="${VERCEL_TOKEN}" \
-              --env "BRANCH_DB_URL=${BRANCH_DB_URL:-}" \
-              2>&1
-          )" || {
-            printf '%s\n' "${deploy_output}"
-            exit 1
-          }
+          deploy_output=""
+          for attempt in 1 2 3; do
+            if deploy_output="$(
+              vercel deploy --prebuilt --yes \
+                --token="${VERCEL_TOKEN}" \
+                --env "BRANCH_DB_URL=${BRANCH_DB_URL:-}" \
+                2>&1
+            )"; then
+              break
+            fi
+            if [ "${attempt}" -eq 3 ]; then
+              printf '%s\n' "${deploy_output}"
+              exit 1
+            fi
+            echo "vercel deploy failed (attempt ${attempt}/3), retrying in 30s..."
+            sleep 30
+          done
           preview_url="$(
             set +o pipefail
             printf '%s\n' "${deploy_output}" \

.gitignore

@@ -62,6 +62,7 @@ vitest.config.*.timestamp*
 .playwright-cli/
 test-results/
 playwright-report/
-
 # Local Claude Code overrides (contributor-specific, not shared)
 **/CLAUDE.local.md
+.tmp_pr*_threads_now.json
+.tmp_pr*_unresolved_slim.json

apps/api/src/routes/v1/wallet/receive/index.ts

@@ -2,22 +2,32 @@ import type { FastifyInstance } from 'fastify';
 import { schema, type Schema } from './schema';
 
 export default async function receiveRoutes(app: FastifyInstance) {
-  app.get<Schema>('/', { schema }, async (request, reply) => {
-    const authToken = request.headers.authorization?.split(' ').at(1);
-    if (authToken == null) return reply.unauthorized();
+  app.get<Schema>(
+    '/',
+    {
+      schema,
+      config: {
+        rateLimit: { max: 100, timeWindow: '1 minute' },
+      },
+    },
+    async (request, reply) => {
+      const authToken = request.headers.authorization?.split(' ').at(1);
+      if (authToken == null) return reply.unauthorized();
 
-    const userAddress = (await app.db.findPersonByAuth({ authToken }))?.address;
-    if (!userAddress) return reply.notFound('User not found');
+      const userAddress = (await app.db.findPersonByAuth({ authToken }))
+        ?.address;
+      if (!userAddress) return reply.notFound('User not found');
 
-    const { chain, tokenId } = request.query;
-    if (tokenId != null) {
-      // TODO: check if user can receive the token
-    }
+      const { chain, tokenId } = request.query;
+      if (tokenId != null) {
+        // TODO: check if user can receive the token
+      }
 
-    return {
-      network: chain,
-      address: userAddress,
-      qr_code_url: `ethereum:${userAddress}`,
-    };
-  });
+      return {
+        network: chain,
+        address: userAddress,
+        qr_code_url: `ethereum:${userAddress}`,
+      };
+    },
+  );
 }