Repo Layout¶

The SutroYaro workspace splits into four layers: read-first docs that load agent context, source code (with the locked harness and the ByteDMD metric), machine-readable research artifacts, and the published mkdocs site. The diagram below groups directories by role rather than enumerating every leaf.

graph LR
    subgraph DOCS["Top-level Docs - read-first stack"]
        README["README.md"]
        CLAUDE["CLAUDE.md"]
        LAB["LAB.md"]
        AGENT["AGENT.md"]
        DISC["DISCOVERIES.md"]
        TODO["TODO.md"]
        CONTRIB["CONTRIBUTING.md"]
        TOOLS["AGENTS.md / CODEX.md / GEMINI.md / AGENT_EVAL.md"]
    end

    subgraph CODE["src/ - Code"]
        BYTEDMD["bytedmd/
primary metric, vendored"]
        SP["sparse_parity/
harness, tracker, training, eval, experiments, challenges"]
        TG["telegram/
TS sync"]
    end

    subgraph OPS["Ops + Tests"]
        BIN["bin/
reproduce-all, run-agent, tg-sync, regen-diagrams"]
        CHECKS["checks/
env_check, baseline_check"]
        TESTS["tests/"]
    end

    subgraph ARTIFACTS["Research Artifacts"]
        RESEARCH["research/
log.jsonl (37 entries), questions.yaml, search_space.yaml"]
        FINDINGS["findings/
41 per-experiment reports"]
        RESULTS["results/
raw numeric outputs"]
        CONTRIBDIR["contributions/
external drop-zone"]
    end

    subgraph SITE["docs/ - mkdocs site"]
        DRESEARCH["research/
findings, surveys, system overviews"]
        DFINDINGS["findings/
per-experiment site pages"]
        DCATCH["catchups/
weekly summaries"]
        DMEET["meetings/, meeting-notes/, lectures/"]
        DGOOGLE["google-docs/
synced"]
        DPROMPTS["agent-prompts/"]
        DTASKS["tasks/
11 task specs + INDEX"]
        DTOOL["tooling/
telegram, automation, agent compat"]
        DDIAG["diagrams/
SVGs"]
    end

    CLAUDE -.points to.-> CODE
    LAB -.governs.-> CODE
    AGENT -.drives.-> ARTIFACTS
    CODE -.writes.-> ARTIFACTS
    ARTIFACTS -.published as.-> SITE
    DOCS -.surfaced on.-> SITE

    style DOCS fill:#fde7c4,stroke:#d4a85a,color:#000
    style CODE fill:#c8e6c9,stroke:#4a8c4f,color:#000
    style OPS fill:#dcedc8,stroke:#7a9a52,color:#000
    style ARTIFACTS fill:#bbdefb,stroke:#4a7fb8,color:#000
    style SITE fill:#e1bee7,stroke:#8e5ba0,color:#000

What each layer does¶

Read-first docs load agent context. A coding agent opens CLAUDE.md, then LAB.md or AGENT.md, then DISCOVERIES.md before touching code.
src/ holds the locked harness, the ByteDMD tracer, training code, the Gymnasium eval environment, and per-experiment scripts.
Ops + tests contain reproducibility checks and the CLI scripts that orchestrate experiments and syncs.
Research artifacts are machine-readable. research/log.jsonl is the append-only experiment log, findings/ holds the prose writeups, results/ holds the numbers.
docs/ is the mkdocs source for cybertronai.github.io/SutroYaro. It mirrors much of the research output in a navigable form and adds meeting notes, weekly catchups, and reusable agent prompts.

Active research front

Day-to-day method work happens in the ByteDMD repo, not here. The current experimental front is cybertronai/ByteDMD/experiments/grid (Yaroslav's self-contained experiments). This workspace is the lab notebook, contributor pipeline, and public site around that work.