Developer Documentation

These pages are for developers and code agents modifying ScienceDiscovery core code. They document current implementation, module ownership, and architecture invariants. For user workflows and precise configuration, use the documentation index.

If this is your first time in the repository, start with the Deep Developer Guide. Do not infer current architecture from a historical feature document.

Start here

• Deep Developer Guide — reading order, code navigation, current architecture facts, change checklist.
• Runtime architecture — native/JiuwenSwarm executors, adapter, API, Runner, and sidecars.
• Repository layout — service/package ownership, dependency rules, and entry points.
• Control plane — authoritative API state, Run lifecycle, and executor seam.

Agent Runtime

• Agent backend reference — current JiuwenSwarm defaults and native-only boundaries.
• Native Agent backend — native loop, models, tools, deadlines, and semantics shared with JiuwenSwarm.
• Runtime Core boundaries — lowest-level contracts of the native executor.
• Dynamic context assembly — native contributors, budgets, traces, dependency boundary.
• Context assembly examples — native model input examples.
• Session trajectory and model context — trajectories, frozen context/state, read-only projections.
• Subagent orchestration — parent/child contracts, handoff, guardrails, failure semantics.

Capability and extension architecture

• Plugin architecture — capability ownership, plugin manifest/runtime/web contracts, host composition.
• MCP tool and protocol design — MCP Sources, tool protocol, permission, audit, control-plane interface.
• Science connectors — scientific-source governance, citation, audit.
• External-source rate limiting — data-source admission, 429 cooldown, boundary with LLM retry.
• Skill Library current implementation — versions, content-addressed packages, search, proposal, publish, rollback.
• Skill progressive disclosure — Skill catalog, frozen snapshots, on-demand reads.
• Skill self-evolution current implementation — proposal → user authorization → new Library version.
• Review and provenance — Artifact Reviewer, claims/evidence, Prompt Manifest.
• ScienceMemory — task/citation graph, storage, module boundaries.
• Evolution sidecar — PUCT/OpenEvolve sidecar contracts and control-plane coupling.
• Idea Tree implementation — Idea Tree runtime, persistence, recovery boundaries.

Execution, storage, and infrastructure

• Single-file binary packaging and releases — build identifiers, package contents, dual-architecture releases, and first-launch bootstrap.
• Deployment runtime internals — local startup chain, remote Runner deployment, Docker internals, and multi-instance behavior.
• Sandbox execution — Bubblewrap/Seatbelt, scientific environments, network, NPU execution.
• Project/Session Runner inheritance — Runner selection, remote execution, inheritance semantics.
• Ascend NPU Host Broker — allowlisted host workloads.
• Network proxy — outbound proxy resolution and security boundary.
• Content-addressable storage — CAS, version objects, workspace change detection.
• PDF worker — PDF extraction protocol and limits.
• Web frontend — Web host, event mapping, frontend development entry points.

Documentation maintenance rules

Developer Docs should describe current implementation or compatibility behavior that still matters.

• Milestone-specific MVP/M1/M2 delivery documents do not stay in the main doc set; use Git history when needed.
• Do not present plans, proposals, or future work as implemented behavior.
• Architecture changes should update architecture.md, repository-layout.md, and the owning subsystem document.
• When documentation conflicts, prefer current source/tests, scripts/start-stack.sh, and scripts/check-architecture.mjs.