scholaraio

Repository Knowledge Design

Status: Current map

Last Updated: 2026-06-12

ScholarAIO is an agent-first research infrastructure. Its published repository knowledge is organized for progressive disclosure: entry docs give agents a map, and the public docs/ tree carries user-facing and durable design material.

This layout is inspired by OpenAI’s harness-engineering guidance that AGENTS.md should behave like a table of contents rather than a monolithic manual: https://openai.com/index/harness-engineering/

Principles

AGENTS.md, CLAUDE.md, and other wrappers stay short and point inward.
Durable facts live in versioned Markdown near the code they govern.
Multi-step procedures live in skills, not in entry docs.
Plans, validation records, and audits are local maintenance artifacts, not published documentation.
Generated references must say how they were generated and when to refresh them.
Agent-facing docs should be easy to index, grep, validate, and garbage collect.

Directory Roles

Path	Role
`docs/index.md`	Public documentation home
`docs/getting-started/`	User setup and upgrade paths
`docs/guide/`	User-facing workflow references
`docs/writing-guide/`	Writing and diagram authoring guides
`docs/api/`	Python API documentation
`docs/design-docs/`	Long-lived architecture and runtime design decisions
`docs/product-specs/`	Product behavior and workflow specifications
`docs/generated/`	Generated facts such as schema or CLI snapshots
`docs/superpowers/`	Local planning artifacts created by superpowers workflows
`docs/archive/` and `docs/internal/`	Historical or local-only notes excluded from published docs

Reading Order

Start with AGENTS.md for hard constraints and navigation.
Use this file for the repository knowledge map.
Use docs/guide/agent-reference.md for agent runtime and skill details.
Use the relevant design doc, product spec, generated reference, or guide before changing a governed area.
Use source code and tests as the final authority for current behavior.

Maintenance Rules

When adding a durable design decision, put it under docs/design-docs/ and link it from docs/design-docs/index.md.
Keep plans, validation evidence, and audits under docs/internal/, which is excluded from the published MkDocs site.
When internal work discovers reusable policy or product behavior, promote only the stable public fact into docs/design-docs/, docs/product-specs/, or a project skill.
When a reference is generated, put it under docs/generated/ and document the generating command in the file header.
Do not use a single root wrapper as the long-term home for checklists, examples, or operational runbooks.

This site is open source. Improve this page.