# ScholarAIO 2.x Public Contract

Status: Current

Last Updated: 2026-07-21

ScholarAIO 2.x is the functional-convergence generation of the project. The
goal of this contract is to make the academic harness dependable while leaving
room for additive improvements to reliability and user experience.

## Product Boundary

ScholarAIO owns the durable academic context and workflow surface around a
coding agent: libraries, evidence, notes, workspaces, skills, CLI operations,
research outputs, and verification helpers. The active agent owns reasoning,
planning, browsing when native browsing is available, delegation, and task
orchestration.

External services and scientific tools are adapters to this harness. They are
not the product's organizing principle and are not assumed to be installed on
the default path.

## Stable Public Surfaces

Within the 2.x line, the following documented surfaces are compatibility
commitments:

- the `scholaraio` console entry point and documented CLI verbs, options, exit
  behavior, and machine-readable outputs;
- documented `config.yaml` keys and environment-variable overrides;
- the fresh runtime layout under `data/libraries/`, `data/spool/`,
  `data/state/`, `workspace/`, and `.scholaraio-control/`;
- canonical skill names, Agent Skills frontmatter, and the documented agent
  discovery paths;
- documented persistent identifiers, workspace paper references, migration
  journals, and supported readers for user-owned data; and
- Python objects explicitly included in the published API reference.

Exact human-facing wording, presentation layout, ranking implementation,
private Python modules, internal service boundaries, and undocumented file
details are not stable APIs.

## Change Policy

- Patch releases fix defects, security issues, documentation, and workflow
  friction without intentionally removing a documented capability.
- Minor releases may add compatible behavior and improve existing workflows,
  but do not open a new product category merely to increase feature breadth.
- Removing or materially changing a stable surface requires a documented
  deprecation for at least one minor release before the next major version,
  except when immediate removal is required for security, data integrity, or a
  third-party service shutdown.
- Persistent data changes require an explicit migration or a compatibility
  reader. Normal startup and package installation must not perform unannounced
  destructive migration.

## Integration Gate

A new third-party integration belongs in ScholarAIO only when all of the
following are true:

1. It improves a core academic workflow for a demonstrated user need.
2. The current agent's native capabilities and existing ScholarAIO surfaces do
   not already provide an adequate path.
3. It has one clear owner and avoids overlapping adapters for the same job.
4. Dependencies and credentials are optional or isolated from the core install.
5. A fixed-corpus or end-to-end smoke test demonstrates the intended value.
6. Missing credentials, network failure, version drift, and unavailability
   degrade to an actionable error or a documented fallback.

Integrations that fail this gate should remain external recipes, sidecars, or
user-managed tools rather than new core capability categories.