Add Pod Naming and Environment Variables Documentation

Summary

This PR adds comprehensive documentation for Grove's pod naming conventions and environment variables for pod discovery. The documentation is organized into two new user guide sections:

1. Pod and Resource Naming Conventions (docs/user-guide/02_pod-and-resource-naming-conventions/) - Explains Grove's hierarchical naming scheme and best practices for naming resources
2. Environment Variables for Pod Discovery (docs/user-guide/03_environment-variables-for-pod-discovery/) - Documents the environment variables Grove injects for pod discovery and coordination and shows examples of how to use them to construct pod fully qualified domain names (FQDN).

Changes

New Documentation Structure

docs/user-guide/02_pod-and-resource-naming-conventions/

• 01_overview.md - Prerequisites and guide overview
• 02_naming-conventions.md - Complete guide covering:
  • Hierarchical pod naming patterns for standalone PodCliques and PodCliqueScalingGroups
  • Kubernetes 63-character name length considerations with scaling headroom calculations
  • Best practices for naming resources (short prefixes like pleader/pworker and dleader/dworker)
  • Why PodClique names must be unique within a PodCliqueSet (reflects Grove's philosophy that each PodClique represents a distinct component with a unique role)
  • Worked example planning names for a complex system
• 03_hands-on-example.md - Deployable multi-node disaggregated inference example demonstrating the naming hierarchy

docs/user-guide/03_environment-variables-for-pod-discovery/

• 01_overview.md - Prerequisites and guide overview
• 02_env_var_reference.md - Reference guide covering:
  • Key distinction between pod names (random suffix) and hostnames (deterministic, DNS-resolvable)
  • How Grove automatically creates headless services for each PodCliqueSet replica
  • Complete reference of all Grove-injected environment variables (GROVE_PCS_NAME, GROVE_PCLQ_NAME, GROVE_PCSG_NAME, etc.)
• 03_hands-on-examples.md - Two worked examples with deployable YAMLs:
  • Standalone PodClique environment variables
  • PCSG with leader-worker pod discovery
• 04_common-patterns-and-takeaways.md - Practical patterns for constructing FQDNs, finding leaders, discovering peers, and key takeaways

New Sample Files

• operator/samples/user-guide/02_pod-and-resource-naming-conventions/multinode-disaggregated-with-frontend.yaml
• operator/samples/user-guide/03_environment-variables-for-pod-discovery/standalone-env-vars.yaml
• operator/samples/user-guide/03_environment-variables-for-pod-discovery/pcsg-env-vars.yaml

Reorganized Existing Files

Documentation Directories - Added numeric prefixes for ordering:

• docs/user-guide/core-concepts/ → docs/user-guide/01_core-concepts/
• docs/user-guide/pod-and-resource-naming-conventions/ → docs/user-guide/02_pod-and-resource-naming-conventions/
• docs/user-guide/environment-variables-for-pod-discovery/ → docs/user-guide/03_environment-variables-for-pod-discovery/

Core Concepts Files - Renamed with numeric prefixes:

• overview.md → 01_overview.md
• pcs_and_pclq_intro.md → 02_pcs_and_pclq_intro.md
• pcsg_intro.md → 03_pcsg_intro.md
• takeaways.md → 04_takeaways.md

Sample YAML Directories - Reorganized to match documentation structure:

• operator/samples/user-guide/concept-overview/ → operator/samples/user-guide/01_core-concepts/
• operator/samples/user-guide/pod-and-resource-naming-conventions/ → operator/samples/user-guide/02_pod-and-resource-naming-conventions/
• operator/samples/user-guide/environment-variables-for-pod-discovery/ → operator/samples/user-guide/03_environment-variables-for-pod-discovery/

All sample YAMLs updated with:

• Documentation reference comments pointing to new paths
• Minimal resource requirements (cpu: 10m, memory: 32Mi) to work on a single real node in KIND clusters

Updated References

• Updated README.md and docs/quickstart.md with links to new documentation structure
• Updated all cross-references between documentation files
• Updated all sample YAML documentation comments

Testing

All commands documented in the guides were tested end-to-end:

• Created KIND cluster with make kind-up FAKE_NODES=40
• Deployed Grove with make deploy
• Successfully ran all kubectl apply, kubectl get pods/pclq/pcsg, kubectl logs, and kubectl exec -- nslookup commands
• Verified environment variables are correctly injected
• Verified DNS resolution works for pod discovery
• Verified all internal documentation links resolve correctly