docs: Rework general overview and features pages (#494)

Signed-off-by: jannfis <[email protected]>

Author: jannfis

docs/features/index.md

@@ -1,36 +1,93 @@
-# Features
+# Features Overview
 
-The `argocd-agent` project provides building blocks to outsource compute in multi-cluster Argo CD setups. The general idea is to install the argocd-application-controller on each managed cluster, while keeping the argocd-server (which includes the API and web UI) on a central control plane cluster. The locations of other components (such as, argocd-redis, argocd-repository-server and argocd-application-controller) vary depending on your needs and requirements. You can read more about this in the [architectural overview](../concepts/architecture.md) section of the docs.
+argocd-agent transforms traditional multi-cluster Argo CD deployments by inverting the connection model: instead of a central control plane reaching out to remote clusters, lightweight agents establish connections back to the hub. This architectural shift enables GitOps at scale across distributed, unreliable, and restricted network environments.
 
-## Implemented
+## Current Capabilities
 
-The following features are available and ready to use with the most recent release of argocd-agent:
+### Core Architecture
 
-* Works with vanilla Argo CD
-* Sync protocol based on gRPC and Cloudevents
-* Synchronization of Application resources between principal and agents
-* Basic synchronization of AppProjects
-* Live resource view of managed resources on the agents
-* Two distinct sync modes for agents: [managed](../concepts/agent-modes/managed.md) and [autonomous](../concepts/agent-modes/autonomous.md)
-* Pluggable authentication methods. Out of the box, mTLS and userpass are supported.
-* Pluggable configuration backend. Out of the box, Kubernetes backend is supported.
-* A CLI to manage agent configuration on the control plane
+**Distributed Compute Model**: Application controllers run locally on workload clusters, reducing control plane load and improving resilience. Each cluster can scale and tune its application controller independently based on local requirements, eliminating the need for complex sharding configurations. The control plane maintains the familiar Argo CD UI and API while agents handle local reconciliation.
 
-## Medium-term road map
+**Pull-Based Connectivity**: Agents initiate all connections to the control plane, eliminating the need for the control plane to have direct network access to workload clusters. This enables deployment across NAT boundaries, firewalls, and air-gapped environments.
 
-The following items are planned to be implemented along the GA (1.0) release of argocd-agent:
+**Vanilla Argo CD Integration**: Works with standard Argo CD installations without requiring custom forks or patches. Components can be deployed in various configurations depending on your scalability and availability requirements.
 
-* [Make desired manifests accessible to principal](https://github.com/argoproj-labs/argocd-agent/issues/344)
-* [Make terminal pods accessible to principal](https://github.com/argoproj-labs/argocd-agent/issues/129)
-* [Make pod logs accessible to principal](https://github.com/argoproj-labs/argocd-agent/issues/128)
-* [Integrate with OpenTelemetry](https://github.com/argoproj-labs/argocd-agent/issues/119)
-* [Integration with SPIFFE for authentication](https://github.com/argoproj-labs/argocd-agent/issues/345)
-* [Compression of data exchanged between principal and agents](https://github.com/argoproj-labs/argocd-agent/issues/113)
+### Operational Modes
 
-## Longer-term road map
+**[Managed Mode](../concepts/agent-modes/managed.md)**: Applications are defined on the control plane and distributed to agents. Ideal for centralized governance and policy enforcement across multiple clusters.
 
-* [High availability for the principal](https://github.com/argoproj-labs/argocd-agent/issues/186)
+**[Autonomous Mode](../concepts/agent-modes/autonomous.md)**: Applications are defined locally on workload clusters and synchronized back for observability. Perfect for edge deployments, air-gapped environments, or scenarios requiring local autonomy.
 
-## Miscellaneous
+### Communication Protocol
 
-We track all bugs and feature requests on our [GitHub issue tracker](https://github.com/argoproj-labs/argocd-agent/issues) and map them to particular releases on our [milestones overview](https://github.com/argoproj-labs/argocd-agent/milestones).
+**gRPC with CloudEvents**: Efficient bi-directional communication using industry-standard protocols. The connection model supports intermittent connectivity and automatic reconnection.
+
+**mTLS Security**: All communication is secured with mutual TLS authentication. Agents authenticate to the principal using client certificates, eliminating the need for the control plane to store cluster credentials.
+
+**Pluggable Authentication**: Extensible authentication framework supporting mTLS and username/password methods out of the box, with plans for SPIFFE integration.
+
+### Resource Management
+
+**Application Synchronization**: Full lifecycle management of Argo CD Applications, including creation, updates, deletion, and status reporting across the distributed architecture.
+
+**AppProject Distribution**: Basic synchronization of AppProjects with mode-specific behavior. Managed agents receive projects from the control plane, while autonomous agents publish their projects for central visibility.
+
+**Live Resource Access**: Transparent proxying of Kubernetes API requests to workload clusters through the control plane, enabling direct resource inspection and manipulation from the central Argo CD interface despite the distributed architecture.
+
+**Custom Resource Actions**: Full support for executing Argo CD resource actions on workload clusters, allowing custom operations and workflows to be triggered from the central control plane.
+
+### Management Tools
+
+**argocd-agentctl CLI**: Command-line tool for managing agent configurations, certificates, and troubleshooting connectivity issues.
+
+**Pluggable Backends**: Extensible storage backend architecture with Kubernetes as the default implementation, designed to support alternative storage solutions for large-scale deployments.
+
+## Development Status
+
+argocd-agent is in active development and **not yet production-ready**. Current functionality provides a solid foundation for the distributed GitOps vision, but several key features are still under development.
+
+### Known Limitations
+
+- **ApplicationSet Support**: Limited support for ApplicationSets in the current implementation
+- **Private Repository Access**: Repository credentials are not synchronized between principal and agents, limiting access to private repositories ([#474](https://github.com/argoproj-labs/argocd-agent/issues/474))
+- **Pod Logs**: Log streaming from workload clusters is not yet implemented
+- **Terminal Access**: Direct pod terminal access through the control plane is planned but not available
+- **High Availability**: Principal component does not yet support high availability configurations
+- **Advanced RBAC**: Multi-tenancy and advanced role-based access control features are still being developed
+
+## Development Roadmap
+
+### Near and Mid-term
+
+**Enhanced Observability**
+
+- [Pod log streaming](https://github.com/argoproj-labs/argocd-agent/issues/128) from workload clusters
+- [Terminal access](https://github.com/argoproj-labs/argocd-agent/issues/129) to pods on remote clusters
+- [Desired manifest access](https://github.com/argoproj-labs/argocd-agent/issues/344) for better debugging
+
+**Protocol Improvements**
+
+- [Private repository support](https://github.com/argoproj-labs/argocd-agent/issues/474) with credential synchronization between principal and agents
+- [Data compression](https://github.com/argoproj-labs/argocd-agent/issues/113) for bandwidth-constrained environments
+- [OpenTelemetry integration](https://github.com/argoproj-labs/argocd-agent/issues/119) for distributed tracing
+- [SPIFFE authentication](https://github.com/argoproj-labs/argocd-agent/issues/345) support
+
+### Long-term Vision
+
+**Scalability Enhancements**
+
+- [High availability](https://github.com/argoproj-labs/argocd-agent/issues/186) for the principal component
+- Alternative storage backends for massive scale deployments
+- Advanced load balancing and sharding strategies
+
+**Enterprise Features**
+
+- Comprehensive multi-tenancy support
+- Advanced RBAC and policy enforcement
+- Integration with enterprise identity providers
+
+## Getting Involved
+
+Development happens in the open on [GitHub](https://github.com/argoproj-labs/argocd-agent). We track all features, bugs, and enhancements in our [issue tracker](https://github.com/argoproj-labs/argocd-agent/issues) and organize them into [milestone releases](https://github.com/argoproj-labs/argocd-agent/milestones).
+
+The project welcomes contributions from the community, whether in the form of code, documentation, testing, or feedback from real-world deployments. Join the conversation in [GitHub Discussions](https://github.com/argoproj-labs/argocd-agent/discussions) or the [#argo-cd-agent](https://cloud-native.slack.com/archives/C07L5SX6A9J) Slack channel.

docs/index.md

@@ -1,27 +1,68 @@
-# Overview
+# argocd-agent - Multi-cluster agent for Argo CD
 
-## About argocd-agent
+**Distributed GitOps at Scale**
 
-The argocd-agent project seeks to enhance the multi-cluster functionality of the popular open-source GitOps tool Argo CD by introducing an agent-based architecture for managing resources across remote clusters.
+argocd-agent reimagines multi-cluster GitOps by flipping the traditional architecture on its head. Instead of a central control plane struggling to reach out to hundreds of remote clusters, lightweight agents establish secure connections back to a unified hub. This fundamental shift unlocks GitOps deployment patterns that were previously impossible or impractical.
 
-Its primary goals are to improve scalability and security as Argo CD expands beyond just a few clusters, while maintaining the features that users love: ease of use, centralized management, and observability.
+## The Challenge
 
-Although the argocd-agent project is still in its early stages and not yet stable, everyone is encouraged to try it out, test it, and contribute.
+Traditional Argo CD multi-cluster deployments face inherent limitations as they scale:
 
-## About this documentation
+- **Network Complexity**: Control planes must maintain direct connections to every managed cluster
+- **Security Boundaries**: Clusters behind NATs, firewalls, or in air-gapped environments are difficult to reach
+- **Operational Overhead**: Complex sharding, credential management, and network troubleshooting
+- **Single Points of Failure**: Centralized application controllers create bottlenecks and reliability risks
 
-This documentation is work-in-progress. It might be outdated, missing important pieces, etc. Feel free to contribute to the documentation by updating, adding and correcting.
+These challenges become exponentially more complex when managing dozens or hundreds of clusters across different networks, cloud providers, and security domains.
 
-We do expect good working knowledge of general Argo CD concepts, architecture and terminology from the reader.
+## The Solution
 
-## License
+argocd-agent introduces a **pull-based architecture** where agents on workload clusters initiate connections to a central control plane. This inversion eliminates most traditional multi-cluster pain points while preserving the familiar Argo CD experience.
+
+**Key Principles:**
+
+- **Agents Connect Inward**: No outbound connections from the control plane
+- **Local Reconciliation**: Application controllers run where workloads live
+- **Unified Observability**: Single pane of glass for all clusters and applications
+- **Standard Argo CD**: Works with vanilla Argo CD installations
+
+See our [Features Overview](./features/index.md) for detailed capabilities and current limitations.
+
+## Project Status
+
+argocd-agent is a **young project in active development**. While not yet production-ready, it already demonstrates the viability of distributed GitOps at scale. The core architecture is stable, and essential features like application synchronization, live resource access, and dual operational modes are working.
+
+**We Need Your Help**
+
+This project thrives on community involvement. Whether you're a GitOps veteran or just curious about distributed architectures, there are many ways to contribute:
 
-The project and all of its code, documentation and assets is available under the Apache 2.0 license.
+- **Test and Experiment**: Try argocd-agent in development environments and share your experience
+- **Report Issues**: Help us identify bugs, edge cases, and missing features  
+- **Contribute Code**: Implement new features, fix bugs, or improve performance
+- **Improve Documentation**: Help make complex concepts more accessible
+- **Share Use Cases**: Tell us about your multi-cluster challenges and requirements
 
-## Architecture
+Every contribution, no matter how small, helps shape the future of distributed GitOps.
 
-Please have a look at the [Architecture](./concepts/architecture.md) docs.
+## Getting Started
 
-## Contributing
+Ready to explore distributed GitOps? Start with our [Getting Started Guide](./getting-started/index.md) to set up a local environment, or dive into the [Architecture Overview](./concepts/architecture.md) to understand how everything fits together.
+
+For existing Argo CD users considering migration, check out our [Migration Guide](./user-guide/migration.md) for a comprehensive transition strategy.
+
+## Community and Support
+
+- **[GitHub Discussions](https://github.com/argoproj-labs/argocd-agent/discussions)** - Ask questions, share ideas, and connect with other users
+- **[#argo-cd-agent](https://cloud-native.slack.com/archives/C07L5SX6A9J)** on CNCF Slack - Real-time community chat
+- **[Issue Tracker](https://github.com/argoproj-labs/argocd-agent/issues)** - Bug reports and feature requests
+- **[Contributing Guide](./contributing/index.md)** - How to get involved in development
+
+## Documentation Notes
+
+This documentation is actively maintained but reflects a rapidly evolving project. Some sections may be incomplete or outdated as we prioritize development velocity. We welcome contributions to improve clarity, accuracy, and completeness.
+
+We assume familiarity with Argo CD concepts, Kubernetes, and GitOps principles. If you're new to these technologies, consider reviewing the [Argo CD documentation](https://argo-cd.readthedocs.io/) first.
+
+## License
 
-We welcome contributions from the community. In order to get started, please take a look at our contribution guide and documentation.
+argocd-agent is open source software released under the [Apache 2.0 License](https://github.com/argoproj-labs/argocd-agent/blob/main/LICENSE).