Opportunities

Ring Opportunities is the supply ↔ demand loop for each clone: members post offers and requests (plus specialized types), Matcher scores interested users, and notifications invite them to connect — without waiting for someone to search the feed.

Traditional boards vs Ring

Matching loop (shared)

Default Matcher install values (ring-config.json → matcher): scoreThreshold 0.7, maxMatches 10, autoApprove false, autoApproveMinScore 0.7, llmConfidenceGate 0.8. Env can override auto-approve via MATCHER_AUTO_APPROVE / MATCHER_AUTO_APPROVE_MIN_SCORE (see features/admin/platform-settings/matcher-config.ts). Cap matches with MAX_MATCHES_PER_OPPORTUNITY.

Eight scoring factors

MatchFactors in lib/ai/types.ts (0–100 each): skillMatch, experienceMatch, industryMatch, locationMatch, budgetMatch, availabilityMatch, careerMatch, cultureMatch. LLM match runs populate this bag; the non-LLM heuristic path in lib/ai/matcher.ts blends skill / tag / location / experience with its own internal weights — do not treat AI-CONTEXT percentage tables as runtime SSOT.

Explanations aim for ≤160 characters (MatchingService truncates longer LLM text). Quality bands in matching results: high ≥80, medium 60–79, low <60 — for analytics, not a published accuracy KPI.

Recommended path

Use the ring-ai-matcher-specialist (or Cursor skill of the same family) with a pause-for-approval prompt:

“Audit this clone’s Opportunities loop: list opportunities.enabledTypes and matcher from ring-config.json, confirm LLM env is set, dry-run create of one offer and one request, report MatchFactors and whether autoApprove would promote pending→active. Do not change platform_settings until I approve.”

Inputs checklist: clone key, admin access, LLM credentials present, sample entity id for organizationId.

Manual path

1. 1

   Set opportunities.enabledTypes and matcher.* in ring-config.json; redeploy or reload config snapshot as your clone does for ring-config.

2. 2

   In Admin → Matcher / AI settings, leave auto-approve off; set scoreThreshold / maxMatches to match your vertical tolerance.

3. 3

   Create a test opportunity from the type selector UI (or POST /api/opportunities); open My Opportunities at /opportunities/my.

4. 4

   Confirm a matched user received a notification and that discovery lists refresh (Tunnel / soft refresh) without inventing a search-index reindex step.

Frequently asked questions

Impact

Will Matcher auto-publish every new listing?

No. Default matcher.autoApprove is false. When enabled, maybeAutoApproveOpportunity still requires score and LLM confidence gates (autoApproveMinScore, llmConfidenceGate).

Do I get a kingdom-wide “95% match accuracy”?

No. Treat historical marketing percentages as deprecated. Use Admin Matcher analytics for your tenant.

Migration

We still have Firestore converters — are they required?

Only when DB_BACKEND_MODE=firebase-full. PostgreSQL clones use opportunity-db-mapper.ts and SerializedOpportunity.

Where did /opportunities/my-opportunities go?

Removed. Canonical dashboard is /opportunities/my via ROUTES.MY_OPPORTUNITIES.

Ops

Why did nobody get notified?

Check LLM availability, Matcher score threshold, maxMatches, and entity block filters in matcher-notification-filter. Notifications go through features/notifications/services/notification-service.

How do collective-order money and jars relate?

Opportunity specializations can carry JSONB metadata (e.g. collective order slots). Community funding jars and builder payout SSOT are documented under Public Pools — do not invent PSP “donation product” APIs as the jar path.

Related documentation

Opportunities

Ring Opportunities is the supply ↔ demand loop for each clone: members post offers and requests (plus specialized types), Matcher scores interested users, and notifications invite them to connect — without waiting for someone to search the feed.

Traditional boards vs Ring

Matching loop (shared)

Default Matcher install values (ring-config.json → matcher): scoreThreshold 0.7, maxMatches 10, autoApprove false, autoApproveMinScore 0.7, llmConfidenceGate 0.8. Env can override auto-approve via MATCHER_AUTO_APPROVE / MATCHER_AUTO_APPROVE_MIN_SCORE (see features/admin/platform-settings/matcher-config.ts). Cap matches with MAX_MATCHES_PER_OPPORTUNITY.

Eight scoring factors

MatchFactors in lib/ai/types.ts (0–100 each): skillMatch, experienceMatch, industryMatch, locationMatch, budgetMatch, availabilityMatch, careerMatch, cultureMatch. LLM match runs populate this bag; the non-LLM heuristic path in lib/ai/matcher.ts blends skill / tag / location / experience with its own internal weights — do not treat AI-CONTEXT percentage tables as runtime SSOT.

Explanations aim for ≤160 characters (MatchingService truncates longer LLM text). Quality bands in matching results: high ≥80, medium 60–79, low <60 — for analytics, not a published accuracy KPI.

Recommended path

Use the ring-ai-matcher-specialist (or Cursor skill of the same family) with a pause-for-approval prompt:

“Audit this clone’s Opportunities loop: list opportunities.enabledTypes and matcher from ring-config.json, confirm LLM env is set, dry-run create of one offer and one request, report MatchFactors and whether autoApprove would promote pending→active. Do not change platform_settings until I approve.”

Inputs checklist: clone key, admin access, LLM credentials present, sample entity id for organizationId.

Manual path

1. 1

   Set opportunities.enabledTypes and matcher.* in ring-config.json; redeploy or reload config snapshot as your clone does for ring-config.

2. 2

   In Admin → Matcher / AI settings, leave auto-approve off; set scoreThreshold / maxMatches to match your vertical tolerance.

3. 3

   Create a test opportunity from the type selector UI (or POST /api/opportunities); open My Opportunities at /opportunities/my.

4. 4

   Confirm a matched user received a notification and that discovery lists refresh (Tunnel / soft refresh) without inventing a search-index reindex step.

Frequently asked questions

Impact

Will Matcher auto-publish every new listing?

No. Default matcher.autoApprove is false. When enabled, maybeAutoApproveOpportunity still requires score and LLM confidence gates (autoApproveMinScore, llmConfidenceGate).

Do I get a kingdom-wide “95% match accuracy”?

No. Treat historical marketing percentages as deprecated. Use Admin Matcher analytics for your tenant.

Migration

We still have Firestore converters — are they required?

Only when DB_BACKEND_MODE=firebase-full. PostgreSQL clones use opportunity-db-mapper.ts and SerializedOpportunity.

Where did /opportunities/my-opportunities go?

Removed. Canonical dashboard is /opportunities/my via ROUTES.MY_OPPORTUNITIES.

Ops

Why did nobody get notified?

Check LLM availability, Matcher score threshold, maxMatches, and entity block filters in matcher-notification-filter. Notifications go through features/notifications/services/notification-service.

How do collective-order money and jars relate?

Opportunity specializations can carry JSONB metadata (e.g. collective order slots). Community funding jars and builder payout SSOT are documented under Public Pools — do not invent PSP “donation product” APIs as the jar path.

Related documentation

Opportunities

Ring Opportunities is the supply ↔ demand loop for each clone: members post offers and requests (plus specialized types), Matcher scores interested users, and notifications invite them to connect — without waiting for someone to search the feed.

Traditional boards vs Ring

Matching loop (shared)

Default Matcher install values (ring-config.json → matcher): scoreThreshold 0.7, maxMatches 10, autoApprove false, autoApproveMinScore 0.7, llmConfidenceGate 0.8. Env can override auto-approve via MATCHER_AUTO_APPROVE / MATCHER_AUTO_APPROVE_MIN_SCORE (see features/admin/platform-settings/matcher-config.ts). Cap matches with MAX_MATCHES_PER_OPPORTUNITY.

Eight scoring factors

MatchFactors in lib/ai/types.ts (0–100 each): skillMatch, experienceMatch, industryMatch, locationMatch, budgetMatch, availabilityMatch, careerMatch, cultureMatch. LLM match runs populate this bag; the non-LLM heuristic path in lib/ai/matcher.ts blends skill / tag / location / experience with its own internal weights — do not treat AI-CONTEXT percentage tables as runtime SSOT.

Explanations aim for ≤160 characters (MatchingService truncates longer LLM text). Quality bands in matching results: high ≥80, medium 60–79, low <60 — for analytics, not a published accuracy KPI.

Recommended path

Use the ring-ai-matcher-specialist (or Cursor skill of the same family) with a pause-for-approval prompt:

“Audit this clone’s Opportunities loop: list opportunities.enabledTypes and matcher from ring-config.json, confirm LLM env is set, dry-run create of one offer and one request, report MatchFactors and whether autoApprove would promote pending→active. Do not change platform_settings until I approve.”

Inputs checklist: clone key, admin access, LLM credentials present, sample entity id for organizationId.

Manual path

1. 1

   Set opportunities.enabledTypes and matcher.* in ring-config.json; redeploy or reload config snapshot as your clone does for ring-config.

2. 2

   In Admin → Matcher / AI settings, leave auto-approve off; set scoreThreshold / maxMatches to match your vertical tolerance.

3. 3

   Create a test opportunity from the type selector UI (or POST /api/opportunities); open My Opportunities at /opportunities/my.

4. 4

   Confirm a matched user received a notification and that discovery lists refresh (Tunnel / soft refresh) without inventing a search-index reindex step.

Frequently asked questions

Impact

Will Matcher auto-publish every new listing?

No. Default matcher.autoApprove is false. When enabled, maybeAutoApproveOpportunity still requires score and LLM confidence gates (autoApproveMinScore, llmConfidenceGate).

Do I get a kingdom-wide “95% match accuracy”?

No. Treat historical marketing percentages as deprecated. Use Admin Matcher analytics for your tenant.

Migration

We still have Firestore converters — are they required?

Only when DB_BACKEND_MODE=firebase-full. PostgreSQL clones use opportunity-db-mapper.ts and SerializedOpportunity.

Where did /opportunities/my-opportunities go?

Removed. Canonical dashboard is /opportunities/my via ROUTES.MY_OPPORTUNITIES.

Ops

Why did nobody get notified?

Check LLM availability, Matcher score threshold, maxMatches, and entity block filters in matcher-notification-filter. Notifications go through features/notifications/services/notification-service.

How do collective-order money and jars relate?

Opportunity specializations can carry JSONB metadata (e.g. collective order slots). Community funding jars and builder payout SSOT are documented under Public Pools — do not invent PSP “donation product” APIs as the jar path.

Related documentation

Typical clone scenarios

1. Talent / partnership ring — enable job, offer, request, partnership; keep Matcher auto-approve off until you trust scoring.
2. Commerce vertical — enable collective_order, scheduled_services, asset_rental, bounty, tender with Wallet / PaymentConductor rails.
3. Ringdom settler / builder ring — enable ring_customization and program so customization quests and institution programs land in CRM.

Operator checklist

1. Confirm feature flag / whitelabel includes opportunities.
2. Set opportunities.enabledTypes in ring-config.json (do not assume every OpportunityType union member is UI-visible).
3. Configure LLM (LLM_PROVIDER, OPENAI_API_KEY or ANTHROPIC_API_KEY, LLM_MODEL) before expecting auto-fill / LLM explanations.
4. Tune Matcher in Admin → Matcher / Platform Settings → AI → Matcher (threshold, max matches, auto-approve).
5. Teach members My Opportunities at /opportunities/my (ROUTES.MY_OPPORTUNITIES) — legacy /opportunities/my-opportunities is removed.

Database: default production clones use DB_BACKEND_MODE=k8s-postgres-fcm (also supabase-fcm). Services return SerializedOpportunity (ISO date strings). Do not invent DATABASE_MODE=firebase_only.

Visibility & status

• Visibility: public | subscriber | member | confidential
• Status: draft | pending | active | closed | expired | archived
• Confidential create/edit requires confidential-capable roles (canCreateOpportunityConfidential / canEditOpportunity)

Role gates (create)

REST surfaces (alpha)

UI forms may still prefer Server Actions in app/_actions/opportunities.ts.

Create (server service)

1. 1

   Authenticate and call createOpportunity with a permitted type. Default type when omitted is offer.

2. 2

   Search with role-aware filters (query, types, budget band, sortBy).

3. 3

   After mutations, rely on syncOpportunityDiscovery (already called from create/update/delete paths): invalidates opportunity cache tags, revalidatePath for /[locale]/opportunities, detail, and /[locale]/opportunities/my, and publishes Tunnel discovery for channel opportunities. This is not a separate full-text index reindex CLI.

LLM / Matcher env (template)

Keys documented in env.local.template: LLM_PROVIDER, OPENAI_API_KEY, ANTHROPIC_API_KEY, LLM_MODEL, MAX_MATCHES_PER_OPPORTUNITY, MATCHING_MAX_TOKENS. Without a working provider, Matcher falls back to non-LLM / tag-style explanations with lower confidence.

Public Pools & DAO Jars

See-also: collective / builder jar payouts tied to opportunity owners.

Typical clone scenarios

1. Talent / partnership ring — enable job, offer, request, partnership; keep Matcher auto-approve off until you trust scoring.
2. Commerce vertical — enable collective_order, scheduled_services, asset_rental, bounty, tender with Wallet / PaymentConductor rails.
3. Ringdom settler / builder ring — enable ring_customization and program so customization quests and institution programs land in CRM.

Operator checklist

1. Confirm feature flag / whitelabel includes opportunities.
2. Set opportunities.enabledTypes in ring-config.json (do not assume every OpportunityType union member is UI-visible).
3. Configure LLM (LLM_PROVIDER, OPENAI_API_KEY or ANTHROPIC_API_KEY, LLM_MODEL) before expecting auto-fill / LLM explanations.
4. Tune Matcher in Admin → Matcher / Platform Settings → AI → Matcher (threshold, max matches, auto-approve).
5. Teach members My Opportunities at /opportunities/my (ROUTES.MY_OPPORTUNITIES) — legacy /opportunities/my-opportunities is removed.

Database: default production clones use DB_BACKEND_MODE=k8s-postgres-fcm (also supabase-fcm). Services return SerializedOpportunity (ISO date strings). Do not invent DATABASE_MODE=firebase_only.

Visibility & status

• Visibility: public | subscriber | member | confidential
• Status: draft | pending | active | closed | expired | archived
• Confidential create/edit requires confidential-capable roles (canCreateOpportunityConfidential / canEditOpportunity)

Role gates (create)

REST surfaces (alpha)

UI forms may still prefer Server Actions in app/_actions/opportunities.ts.

Create (server service)

1. 1

   Authenticate and call createOpportunity with a permitted type. Default type when omitted is offer.

2. 2

   Search with role-aware filters (query, types, budget band, sortBy).

3. 3

   After mutations, rely on syncOpportunityDiscovery (already called from create/update/delete paths): invalidates opportunity cache tags, revalidatePath for /[locale]/opportunities, detail, and /[locale]/opportunities/my, and publishes Tunnel discovery for channel opportunities. This is not a separate full-text index reindex CLI.

LLM / Matcher env (template)

Keys documented in env.local.template: LLM_PROVIDER, OPENAI_API_KEY, ANTHROPIC_API_KEY, LLM_MODEL, MAX_MATCHES_PER_OPPORTUNITY, MATCHING_MAX_TOKENS. Without a working provider, Matcher falls back to non-LLM / tag-style explanations with lower confidence.

Public Pools & DAO Jars

See-also: collective / builder jar payouts tied to opportunity owners.

Typical clone scenarios

1. Talent / partnership ring — enable job, offer, request, partnership; keep Matcher auto-approve off until you trust scoring.
2. Commerce vertical — enable collective_order, scheduled_services, asset_rental, bounty, tender with Wallet / PaymentConductor rails.
3. Ringdom settler / builder ring — enable ring_customization and program so customization quests and institution programs land in CRM.

Operator checklist

1. Confirm feature flag / whitelabel includes opportunities.
2. Set opportunities.enabledTypes in ring-config.json (do not assume every OpportunityType union member is UI-visible).
3. Configure LLM (LLM_PROVIDER, OPENAI_API_KEY or ANTHROPIC_API_KEY, LLM_MODEL) before expecting auto-fill / LLM explanations.
4. Tune Matcher in Admin → Matcher / Platform Settings → AI → Matcher (threshold, max matches, auto-approve).
5. Teach members My Opportunities at /opportunities/my (ROUTES.MY_OPPORTUNITIES) — legacy /opportunities/my-opportunities is removed.

Database: default production clones use DB_BACKEND_MODE=k8s-postgres-fcm (also supabase-fcm). Services return SerializedOpportunity (ISO date strings). Do not invent DATABASE_MODE=firebase_only.

Visibility & status

• Visibility: public | subscriber | member | confidential
• Status: draft | pending | active | closed | expired | archived
• Confidential create/edit requires confidential-capable roles (canCreateOpportunityConfidential / canEditOpportunity)

Role gates (create)

REST surfaces (alpha)

UI forms may still prefer Server Actions in app/_actions/opportunities.ts.

Create (server service)

1. 1

   Authenticate and call createOpportunity with a permitted type. Default type when omitted is offer.

2. 2

   Search with role-aware filters (query, types, budget band, sortBy).

3. 3

   After mutations, rely on syncOpportunityDiscovery (already called from create/update/delete paths): invalidates opportunity cache tags, revalidatePath for /[locale]/opportunities, detail, and /[locale]/opportunities/my, and publishes Tunnel discovery for channel opportunities. This is not a separate full-text index reindex CLI.

LLM / Matcher env (template)

Keys documented in env.local.template: LLM_PROVIDER, OPENAI_API_KEY, ANTHROPIC_API_KEY, LLM_MODEL, MAX_MATCHES_PER_OPPORTUNITY, MATCHING_MAX_TOKENS. Without a working provider, Matcher falls back to non-LLM / tag-style explanations with lower confidence.

Public Pools & DAO Jars

See-also: collective / builder jar payouts tied to opportunity owners.