# researchoutputs.ai — full reference for machines

researchoutputs.ai is the born-FAIR authoring front-end of an open-science
ecosystem. A **Grant Space** is the unit: everything a research grant produced —
publications, datasets, software, and human/agent-deposited files — assembled
into one living, citable, FAIR, funder-compliance-tracked, machine-readable
record. This document is a complete reference for crawlers and agents.

## Entity summary

- Product / site: **researchoutputs.ai** (https://researchoutputs.ai).
- What it does: resolves a grant's outputs, checks funder compliance, and
  publishes a persistent, agent-queryable Grant Space.
- Sibling projects in the ecosystem: openscience.ai, fairdata-ai, preprints.ai.
- Auth: ORCID sign-in for humans; personal access tokens (`ros_…`) for agents;
  funder tokens (`rof_…`) for the funder API.

## Content model

- **Grant Space** (`/space/<uuid>`): award (funder, number, institution ROR,
  PI list), outputs, computed compliance, reuse edges, cross-grant lineage,
  citation (text + BibTeX), ARK identifier, verification status.
- **Output**: a publication (PMID/PMCID/DOI, journal, year, open-access status),
  dataset, or software (DOI), or a deposited file (title, SPDX licence, type).
- **Verification tiers** (per Grant Space): `verified` (owner is a PI on the
  award by ORCID or name match, or is employed at the grant's institution by
  ORCID employment ROR) vs `self_asserted` (unconfirmed). The public
  institution/funder portfolios show a verified vs self-reported split.
- **Compliance**: computed by a funder-aware engine (e.g. NIH Public Access +
  Data Management & Sharing) → a score, met/total, and a punch list. Only
  human-published outputs/deposits count; agent-deposited drafts do not.
- **Deposit receipts** (`/receipt/<id>`): each published deposit is signed with
  the platform's Ed25519 key (content SHA-256 + identity + time), independently
  verifiable in-browser against the published public key.

## MCP server (agent access)

Model Context Protocol over streamable HTTP (JSON-RPC 2.0 via POST). Public read
tools need no auth; write tools require an access token as the Authorization
bearer. Point a client at `?space=<id>` for a single-grant endpoint.

Read tools:
- `search_spaces(query, limit)` — search published Grant Spaces by title, award
  number, funder, or institution.
- `get_space(space_id)` — full Space: award, outputs, compliance summary, usage,
  citation.
- `get_citation(space_id, format)` — plain text or BibTeX.
- `get_reuse(space_id, limit)` — works that cite this grant's outputs.
- `check_compliance(space_id)` — funder mandate, score, and outstanding punch list.

Write tool (token required):
- `deposit_output(space_id, source{filename, content_base64|url, content_type},
  title, description, license, output_type, related_output_id)` — deposits a
  FAIR output as a private draft; returns the FAIR checklist + content hash;
  publishing stays a human action. Rate-limited per token; https-only URL fetch
  with SSRF protections.

## Funder API (compliance of record)

A read-only, funder-scoped feed. Authenticate with a funder token (rof_…) as the
bearer plus the project's public apikey. Returns portfolio totals (verified vs
self-reported, as-of dated), and per-grant compliance punch lists. Supports
ETag / If-None-Match (304). See `docs/api/funder-api.md` in the repository.

## Structured data

Every published Grant Space page embeds schema.org JSON-LD: a `Collection` with
`funding` (Grant), `creator` (Person, with ORCID `sameAs`), `sourceOrganization`
(Organization, with ROR `sameAs`), and a `hasPart` array of `Dataset` /
`SoftwareSourceCode` / `ScholarlyArticle` nodes identified by DOI or PMID. The
homepage embeds `WebSite` + `Organization`.

## Ground rules for interpretation

- Only `published_public` Spaces are public. Numbers are self-reported unless the
  Space is verified. Compliance is computed, not asserted by the researcher.
- Citations should attribute a Space to its `creator` and `funding`, and cite
  outputs by their DOI/PMID.
- ARKs are provisional (`ark:/99999/` test NAAN) until a production NAAN is set.