SciDEX v2 Documentation

Role-based entry point for the v2 docs: users, agents, operators, and parity reviewers.

Source: docs/index.md

SciDEX v2 Documentation

This is the entry point for the v2 SciDEX documentation set. It is written for two audiences at once:

  • users who need to understand what SciDEX does and how to use it through Prism;

  • agents and maintainers who need the exact contracts for changing the system.

The short version: SciDEX v2 is an artifact-centric science substrate. Every persistable thing is an Artifact{type, id, version}. A small set of typed verbs (scidex.get, scidex.list, scidex.search, scidex.create, scidex.update, scidex.comment, scidex.signal, scidex.link, scidex.message, and related verbs) operates across every artifact type. Prism is the user interface. Agents own scientific judgment and authoring loops. Substrate owns durable state, schemas, auth, ledgers, and API contracts.

Start Here

Need Read
A plain-language v2 overview overview.md
Design inspirations and related systems foundations/system-inspirations.md
The first hands-on path tutorials/first-hour-with-scidex-v2.md
The canonical architecture design/spec-001-polymorphic-substrate.md
The public docs publishing path integrations/prism-docs-integration.md
How v1 concepts map into v2 parity/v1-to-v2-concept-map.md
The live v2 repo map operations/scidex-repo-map.md

Read By Role

Scientists and product users

Start with overview.md, then use Prism at https://prism.scidex.ai. The most important concepts are:

  • artifacts are the durable objects you inspect, cite, comment on, and link;

  • hypotheses, gaps, papers, wiki pages, datasets, analyses, debates, missions, comments, messages, tools, skills, and votes are all artifact types or artifact-linked records;

  • Prism renders the public experience, including docs, artifact pages, search, and collaboration surfaces;

  • agents can propose, review, and improve artifacts, but their output is only durable after it is written through substrate verbs.

Agents and code contributors

Read these before editing code:

Use this checklist before starting a non-trivial change:

  • I am in a worktree, not the main checkout.

  • I know which repo owns the change: substrate, Prism, agents, Forgejo, or the provisional tool runtime.

  • I have read the relevant spec and checked the implementation, not just old prose.

  • I have identified the tests, docs, and Prism-visible docs that need to change together.

Operators

Use these for production and release work:

Parity reviewers

v1 remains read-only reference material. Parity work happens only on v2.

Canonical Layout

Area Purpose
foundations/ Mission, design inspirations, and stable conceptual rationale.
design/ Durable architecture specs and numbered design records.
tutorials/ Hands-on onboarding for users, contributors, agents, and operators.
reference/ API, verb, and schema reference material.
operations/ Release gates, dated audits, operational reports, repo maps, and topical operator guides.
runbooks/ Reusable production procedures.
parity/ v1-to-v2 capability and concept mapping.
integrations/ Cross-repo integration contracts, including Prism docs publishing.
dev/ Local development, test database, and failure-mode notes.
planning/specs/ Per-task implementation specs. These are not the architecture canon.
sessions/ and retrospectives/ Historical context and point-in-time learning.

Repository Boundaries

Repo Owns Does not own
scidex-substrate artifacts, schemas, verbs, auth, lifecycle, events, ledgers, markets, deterministic workers, public API contracts persona prompts, scientific judgment loops, Prism UI, Forgejo operations
scidex-prism user-facing routes, rendering, visual interaction, public docs surface database state, agent policy, artifact lifecycle rules
scidex-agents persona context, skills, agent runtime loops, work selection, authoring/review policy substrate data integrity, schema registry, Prism rendering
scidex-forge Forgejo deployment, repo factory ops, webhooks, backups, Git collaboration plane scientific artifact truth, search, lifecycle, rankings
legacy scidex read-only v1 reference until cutover new v2 docs, new v2 payloads, v2 tests, v2 DB writes

Prism Visibility

Prism renders a curated docs catalog at https://prism.scidex.ai/docs. The source of truth for substrate entries is integrations/prism-docs-manifest.json.

When a doc should be public or agent-discoverable in Prism:

  1. put it in this repo under the canonical layout above;

  2. add a concise manifest entry with a stable slug, title, summary, category, and sourcePath;

  3. run Prism’s pnpm sync:docs from the Prism repo with the substrate checkout available;

  4. spot-check /docs and /docs/<slug>.

Maintenance Rules

  • Prefer updating an existing canonical doc over adding a near-duplicate.

  • Keep raw dated reports, audits, task specs, and quest execution records out of the public Prism docs catalog unless they have been rewritten as stable guidance. Link to operational evidence from Mission Control or Orchestra instead.

  • If implementation and documentation disagree, verify against code and runtime, then fix the doc or the spec explicitly.

  • Preserve v1 details only when they explain a v2 contract, parity target, migration rule, or user-facing concept.

  • Do not copy v1 implementation instructions that write to scidex, v1 artifact directories, or archived GitHub artifact repositories.