README.md

Documentation

This folder contains human-facing documentation for operators, advanced operators, and contributors.

• Operators should start with getting-started.md and operator-guide.md.
• Advanced operators should read operator-advanced-guide.md, control-plane.md, agent-hosting.md, observability.md, and security-and-data-sovereignty.md.
• Contributors should start with contributor-guide.md, then use the development, testing, module, connector, telemetry, and client integration guides.

Agent-specific compressed context lives in .agents/30-context. Agent-specific mandatory constraints live in .agents/20-guardrails.

---

For Operators

Document	Purpose
getting-started.md	Zero to first successful run
operator-guide.md	Primary operator manual
package-guide.md	Practical guide to the migration package
configuration-guide.md	Common configuration patterns
configuration-reference.md	Full configuration schema reference
scenarios-guide.md	Scenario files and how to use them
cli-guide.md	CLI commands and options
tui-guide.md	Terminal UI usage
ui-mode-contract.md	Canonical CLI/TUI mode-to-view contract
migration-process-guide.md	Migration phases end to end
capabilities-guide.md	What can be migrated
troubleshooting-guide.md	Diagnosing common failures

For Advanced Operators

Document	Purpose
operator-advanced-guide.md	Many jobs, large organisations, operational diagnostics
control-plane.md	Control Plane responsibilities, endpoints, lifecycle
agent-hosting.md	How agents run — local, hosted, container, TFS
observability.md	Traces, metrics, logs, dashboards
security-and-data-sovereignty.md	Security and data residency

For Contributors

Document	Purpose
contributor-guide.md	Primary contributor entry point
development-setup.md	Development environment setup
testing-guide.md	Testing model and conventions
live-system-testing-guide.md	Live Azure DevOps and TFS test setup, CI gating, and troubleshooting
module-development-guide.md	Adding and modifying modules
connector-development-guide.md	Adding and modifying connectors
telemetry-development-guide.md	Adding telemetry correctly
client-integration-guide.md	Azure DevOps and TFS SDK integration
package-boundary-reference.md	Caller-facing package boundary, routing ownership, and persistence model

Reference

Document	Purpose
architecture.md	Full architectural explanation
package-boundary-reference.md	Contributor reference for IPackageAccess and package routing ownership
package-format-reference.md	Precise package format reference
validation.md	Validation model (four-tier)
ui-mode-contract.md	Exact CLI/TUI mode and view contract
work-item-iteration-guide.md	Work item iteration patterns
concurrent-write-detection.md	Concurrent write detection and lease protocol
adr/	Architecture Decision Records