the-rfp-hub

# RFP Hub

[![CI](https://github.com/The-RFP-Hub/the-rfp-hub/actions/workflows/ci.yml/badge.svg)](https://github.com/The-RFP-Hub/the-rfp-hub/actions/workflows/ci.yml)
[![code: MIT](https://img.shields.io/badge/code-MIT-blue.svg)](./LICENSE)
[![standard: CC0-1.0](https://img.shields.io/badge/standard-CC0--1.0-lightgrey.svg)](./packages/standard/LICENSE)

An open, neutral aggregation layer and **standard** for **Ethereum-ecosystem funding
opportunities** — grants, hackathons, bounties, accelerators, VC funds, and RFPs. It indexes,
verifies, and distributes opportunities through a standard format, a public API, open data
exports, and agent-friendly tooling (M2 ships these as running, tested code) — and where an entry
carries an **application link**, it sends you to the
opportunity's own submission channel to apply. (Carrying one is ingestion policy on the Hub's own
data, with named exceptions — four of the 142 seeded entries have no public application URL, each
documented in [the API README](./packages/api/README.md); the schema itself leaves
`applicationUrl` optional, so third-party documents may omit it.)

That link (`applicationUrl`) is the single link-back target in the standard, and it carries
whatever the submission channel actually is — an application portal, a form, or a forum thread
where no portal exists. The Hub is where you find the opportunity, never where you apply.

pnpm monorepo. The hand-authored **JSON Schema is the single source of truth**; TypeScript types
are generated from it, and every other format the standard does or doesn't ship is listed in
[`ARTIFACTS.md`](./packages/standard/ARTIFACTS.md).

## The Standard

The heart of the project is the **RFP Hub Standard** — a versioned, documented, validated
JSON Schema (draft 2020-12) describing a funding opportunity. It's published as
[`@the-rfp-hub/standard`](./packages/standard) (CC0-1.0) and ships generated TypeScript types.

- Schema: [`packages/standard/schemas/v1.0.1/opportunity.schema.json`](./packages/standard/schemas/v1.0.1/opportunity.schema.json)
- Field reference: [`FIELDS.md`](./packages/standard/schemas/v1.0.1/FIELDS.md)
- Status of this version (maturity, known issues): [`STATUS.md`](./packages/standard/schemas/v1.0.1/STATUS.md)
- Prior-art crosswalk (DAOIP-5 · schema.org/Grant): [`CROSSWALK.md`](./packages/standard/schemas/v1.0.0/CROSSWALK.md)
- Validated against real-world funding data: [`BENCHMARK.md`](./packages/standard/schemas/v1.0.0/BENCHMARK.md)
- What's normative vs. informative: [`NORMATIVE.md`](./packages/standard/NORMATIVE.md)

Validate anything against it:

```bash no-run
npx rfphub-validate opportunity.json
```

## Packages

| Package | npm | License | Purpose |
|---|---|---|---|
| `packages/standard` | `@the-rfp-hub/standard` | CC0-1.0 | Canonical JSON Schema, generated TS types, registries, conformance suite, migration table. Zero runtime deps. **SSoT.** |
| `packages/validate` | `rfphub-validate` | MIT | `npx rfphub-validate` CLI + typed validation library, with an advisory warning tier over the registries. |
| `packages/api` | — | MIT | Public `/v1/` REST API (Fastify + Postgres), plus the authenticated write, review and administration surfaces. |
| `packages/frontend` | — | MIT | RFP Hub frontend (Next.js) — the public directory and the publisher dashboard: submit, claim, review, keys, and per-entry analytics, one app and one deploy pipeline for both. See [`packages/frontend/README.md`](./packages/frontend/README.md). |
| `packages/client` | `@the-rfp-hub/client` | MIT | Typed HTTP client *(planned)*. |
| `packages/mcp` | `@the-rfp-hub/mcp` | MIT | Model Context Protocol server (stdio): search and fetch opportunities from any MCP client, plus an optional write behind an approval a person grants at their own terminal. See [`packages/mcp/README.md`](./packages/mcp/README.md) and [`adr/0012`](./adr/0012-mcp-server-per-user-credential-stdio-out-of-band-approval.md). |
| [`skills/funding-search`](./skills/funding-search/SKILL.md) | — | MIT | Agent Skill for searching funding opportunities — prefers the MCP server when installed, otherwise a bundled zero-dependency Node script. See [`skills/README.md`](./skills/README.md) for install channels (multi-agent installer, Claude Code plugin marketplace, or manual copy). |

Every package takes its *contract* from `@the-rfp-hub/standard` alone, and never reaches into
another package's internals (dependency inversion at the package level). The only non-Standard
cross-package dependency is `packages/api` → `rfphub-validate`, through that package's published
API, so the Hub validates with the same reference implementation everyone else runs.

**Two version axes.** A package's `version` is its npm distribution version and moves freely; the
**spec version** (`1.0.1`, in `specVersion` and the schema `$id`) is the data contract and moves
only under [`PROCESS.md`](./packages/standard/PROCESS.md). They are different numbers on purpose.

## Governance

The standard is governed by written process, not by whoever is around:

- [`GOVERNANCE.md`](./GOVERNANCE.md) — editors, the decision rule, review windows, appeals,
  non-discrimination and ranking (what decides indexing, what never does, and why there is no paid
  placement), and the list of things this project deliberately does *not* have.
- [`REVIEW-CRITERIA.md`](./REVIEW-CRITERIA.md) — what a reviewer checks on a single submitted
  listing, what is explicitly not a criterion, what "pending" means, and who decides.
- [`PUBLISHERS.md`](./PUBLISHERS.md) — how an organization becomes a verified publisher, claims an
  entry, and how verification is revoked.
- [`packages/standard/PROCESS.md`](./packages/standard/PROCESS.md) — feature stages, what
  "breaking" means operationally, deprecation, how to register a vocabulary value, the
  [RFC process](./packages/standard/PROCESS.md#rfc-process) routing table, the release checklist.
- [`adr/`](./adr) — the decision records behind the shape of the data model.

## Guides

[`docs/`](./docs) holds the handoff guides — four documents, each written for one person doing one
job, linking to the per-package detail rather than duplicating it:

- [`docs/deployment.md`](./docs/deployment.md) — what runs where, what must exist in the cloud
  account **before** the first deploy (there is no infrastructure-as-code), the required variables,
  the first-deploy sequence, rollback, the manual npm release runbook, and the three ways to deploy
  a copy of the frontend.
- [`docs/api-integration.md`](./docs/api-integration.md) — a five-minute read-only quickstart, the
  write flow from an email address to a publishing key, the scope table, and the nine contracts
  that surprise integrators.
- [`docs/publisher-onboarding.md`](./docs/publisher-onboarding.md) — for whoever operates the Hub:
  running a publisher application end to end, refusing one, revoking verification, and deciding a
  disputed claim.
- [`docs/external-deploy-test.md`](./docs/external-deploy-test.md) — the two-hour protocol that
  proves an outside developer can deploy a frontend against the public API from the docs alone.

Every shell block in those guides is marked `no-run`, `safe-read` or `staging-write`; the
convention is defined in [`docs/README.md`](./docs/README.md).

## Deploy your own copy, or install the skill

**Deploy your own copy of the frontend** with the one-click Deploy Button in
[`packages/frontend/README.md`](./packages/frontend/README.md#deploying-your-own-copy). It lives in
exactly one place on purpose — a Deploy Button URL carries the whole build configuration in its
query string, so a second copy of the button is a second configuration that drifts. The other two
paths, and the read-only limitation every copy inherits, are in
[`docs/deployment.md` §9](./docs/deployment.md#9-the-frontend-three-ways-to-deploy-a-copy).

**Install the agent skill** through any of three channels, all of which install the same directory:

```sh no-run
# 1. multi-agent installer: detects the agents you have and copies the skill into each
npx skills add The-RFP-Hub/the-rfp-hub --skill funding-search

# 2. Claude Code plugin marketplace
claude plugin marketplace add The-RFP-Hub/the-rfp-hub
claude plugin install rfp-hub@rfp-hub

# 3. a plain copy into whichever agent's skill directory applies
cp -R skills/funding-search ~/.claude/skills/
```

Every agent's directory, with the citation for each, is in
[`skills/README.md`](./skills/README.md).

## Repo topology

Developed as one pnpm workspace for fast iteration (the schema and its generated types move
together in a single change), and published as independent npm packages. At handoff the
packages can be split into per-component repos (`the-rfp-hub/standard`, `the-rfp-hub/validate`,
…) via `git subtree split`. The per-package `LICENSE`, `README` and `package.json` provide the
metadata for a future split. Before splitting, replace `workspace:*` dependencies with registry
ranges and verify standalone install, build and test; `packages/api` is not published.

## Develop

```bash no-run
pnpm install
pnpm codegen        # regenerate TS types from the JSON Schema
pnpm codegen:check  # fail if generated types drift from the schema (CI gate)
pnpm build          # build all packages
pnpm test           # run the test suite (vitest)
pnpm typecheck
pnpm lint           # biome
```

**Already have a dev database from M2?** It needs one upgrade before the current migrations will
apply. `packages/api/docker-compose.yml` now pins `pgvector/pgvector:pg15` instead of
`postgres:15-alpine`, because `CREATE EXTENSION vector` ships as a migration. Same major version, so
the data directory is compatible and the named volume is reused — but the C library underneath
changes with the image, and with it the collation provider. Run the script; it dumps first, refreshes
the collation version, reindexes, migrates, and compares row counts before and after:

```bash no-run
packages/api/scripts/upgrade-dev-postgres.sh
```

It takes no argu