Repository structure

Crates

crates/
  uuldana-core/          # pure contracts and contract tests
  uuldana-provider-sdk/  # adapter-facing exports and example adapters
  uuldana-transport/     # PTY, ACP and custom CLI process transports
  uuldana-runtime/       # supervisor, relay, ACP, journal, config, cooldown, handoff, orchestrator
  uuldana-providers/     # finding programs, learning adapters from their help, manifest adapters
  uuldana-cli/           # the uuldana binary
vendor/
  portable-pty/          # patched dependency, see its UULDANA_PATCH.md
  subc-jobobject/        # patched dependency

Other top-level folders: scripts/ (Windows setup, verification, release packaging), examples/ (a sample config.json and a provider manifest), packaging/ (the local npm packages), tools/ (the test process helper), and docs/. The recorded --help texts used as test data are in crates/uuldana-providers/tests/fixtures/help/.

Architecture references

• docs/ARCHITECTURE.md: boundaries, ownership, events, permissions, and the failover flow.
• docs/CONFIGURATION.md: every field of config.json.
• docs/PROVIDER_SDK.md: adapter authoring rules, manifests, and examples.
• docs/PLUGIN_COMPATIBILITY.md: what carries over between providers.
• docs/CONTRACT_FREEZE.md: frozen public interfaces and the contract hash.
• docs/adr/: accepted architecture decision records.
• docs/PROTOCOL_COMPATIBILITY.md: protocol findings and explicit unknowns.
• docs/RELEASING.md: how a release is prepared.

Verification and platform work

docs/WINDOWS_DEVELOPMENT.md describes toolchains and verification scripts. The Phase 1 reports preserve failures as well as passing checks.

Vendored portable-pty and subc-jobobject carry narrowly scoped Windows patches and provenance notes. Their presence does not authorize changing frozen core contracts.