Created the repository documentation

docs/INDEX.md

@@ -0,0 +1,118 @@
+# Linux Setup Script — Documentation Index
+
+This directory contains the comprehensive technical documentation for the
+`linux-setup-script` repository. The documentation is intended to serve as a
+persistent knowledge base for future coding agents, eliminating the need to
+repeatedly reverse-engineer the repository from source.
+
+## Root Document Map
+
+| Document | Location | Purpose |
+|----------|----------|---------|
+| ARCHITECTURE.md | Repository root | High-level architecture (not present) |
+| SECURITY.md | Repository root | Security model and threat mitigations (not present) |
+| ROADMAP.md | Repository root | Future development plans (not present) |
+| PRIVACY.md | Repository root | Data handling and privacy (not present) |
+| LICENSE | Repository root | License terms (not present) |
+
+## Documentation Catalogue
+
+### Core Architecture
+
+| File | Description |
+|------|-------------|
+| [architecture.md](./architecture.md) | High-level architecture, component relationships, dependency direction |
+| [repository-overview.md](./repository-overview.md) | Repository purpose, scope, supported platforms, entry points |
+| [repository-structure.md](./repository-structure.md) | Source tree layout, module organisation, naming conventions |
+| [design-decisions.md](./design-decisions.md) | Key architectural/design choices and rationale |
+| [dependencies.md](./dependencies.md) | External and internal dependencies |
+
+### Configuration & Data
+
+| File | Description |
+|------|-------------|
+| [configuration.md](./configuration.md) | Configuration schema, sources, precedence, derivation |
+| [data-model.md](./data-model.md) | Domain entities, relationships, persistence |
+| [state-and-persistence.md](./state-and-persistence.md) | State management, stores, caches, migrations |
+
+### Components
+
+| File | Description |
+|------|-------------|
+| [components/foundation-layer.md](./components/foundation-layer.md) | Core utilities: filesystem, execution, system-info, package management |
+| [components/configuration-management.md](./components/configuration-management.md) | Config file manipulation (INI, JSON, XML, GSettings, modprobe) |
+| [components/package-management.md](./components/package-management.md) | Unified package manager abstraction layer |
+| [components/service-management.md](./components/service-management.md) | systemd/OpenRC service control |
+| [components/permission-management.md](./components/permission-management.md) | Flatpak/GNOME/Android permission management |
+| [components/hardware-integration.md](./components/hardware-integration.md) | Device-specific hardware setup (Argon ONE UP, GPU, laptop power) |
+
+### Execution Flows
+
+| File | Description |
+|------|-------------|
+| [flows/startup-and-provisioning.md](./flows/startup-and-provisioning.md) | Complete run.sh execution flow from entry to completion |
+| [flows/package-management.md](./flows/package-management.md) | Repository config, package install/update/cleanup flow |
+| [flows/configuration-deployment.md](./flows/configuration-deployment.md) | RC files, resources, profiles deployment flow |
+| [flows/system-configuration.md](./flows/system-configuration.md) | Kernel, sysctl, modprobe, GRUB, GNOME configuration flow |
+| [flows/git-setup.md](./flows/git-setup.md) | GPG/SSH key generation and Git configuration flow |
+
+### Behaviours
+
+| File | Description |
+|------|-------------|
+| [behaviour/theme-and-font-resolution.md](./behaviour/theme-and-font-resolution.md) | Theme variant, font sizing, DPI/resolution adaptation |
+| [behaviour/desktop-environment-configuration.md](./behaviour/desktop-environment-configuration.md) | GNOME, KDE, MATE, LXDE, Phosh specific configurations |
+| [behaviour/application-launcher-customisation.md](./behaviour/application-launcher-customisation.md) | .desktop file modifications for 100+ applications |
+| [behaviour/autostart-and-default-apps.md](./behaviour/autostart-and-default-apps.md) | User autostart entries and mimeapps.list associations |
+| [behaviour/directory-and-file-management.md](./behaviour/directory-and-file-management.md) | XDG directories, hidden files, symlinks, templates |
+
+### Integrations
+
+| File | Description |
+|------|-------------|
+| [integrations/package-managers.md](./integrations/package-managers.md) | pacman, apt, apk, pkg, Flatpak, Cargo, GitHub releases |
+| [integrations/display-servers.md](./integrations/display-servers.md) | Wayland, X11, tty detection and adaptation |
+| [integrations/desktop-environments.md](./integrations/desktop-environments.md) | GNOME, KDE, MATE, LXDE, Phosh integrations |
+| [integrations/hardware.md](./integrations/hardware.md) | Argon ONE UP, GPU, laptop power, audio, WiFi |
+| [integrations/bootloader.md](./integrations/bootloader.md) | GRUB multi-boot entries, mkinitcpio |
+| [integrations/platforms.md](./integrations/platforms.md) | Android/Termux, SteamOS, WSL, immutable distros |
+
+### Cross-Cutting Concerns
+
+| File | Description |
+|------|-------------|
+| [testing.md](./testing.md) | Test strategy, organisation, coverage (manual verification) |
+| [concurrency-and-scheduling.md](./concurrency-and-scheduling.md) | Sequential execution, privilege separation, no parallelism |
+| [error-handling.md](./error-handling.md) | Error taxonomy, handling patterns, failure isolation |
+| [logging.md](./logging.md) | Logging framework, levels, structured fields, sinks |
+| [invariants.md](./invariants.md) | System-wide invariants and contracts |
+| [build-and-deployment.md](./build-and-deployment.md) | No build pipeline; direct script execution |
+| [security.md](./security.md) | Privilege escalation, SSH/GPG, Flatpak permissions, hardening |
+| [ambiguities-and-open-questions.md](./ambiguities-and-open-questions.md) | Unresolved items, TODOs, known gaps |
+| [change-guide.md](./change-guide.md) | How to modify common areas safely |
+| [documentation-maintenance.md](./documentation-maintenance.md) | How to keep docs current, ownership |
+
+## Navigation Aids
+
+### Start Here (Newcomers)
+1. [repository-overview.md](./repository-overview.md) — Understand what this repository does
+2. [architecture.md](./architecture.md) — Understand the high-level structure
+3. [flows/startup-and-provisioning.md](./flows/startup-and-provisioning.md) — Understand the main execution flow
+
+### Deep Dive (Component Owners)
+- [components/foundation-layer.md](./components/foundation-layer.md) — Core utilities
+- [components/package-management.md](./components/package-management.md) — Package abstraction
+- [components/configuration-management.md](./components/configuration-management.md) — Config manipulation
+- [integrations/desktop-environments.md](./integrations/desktop-environments.md) — DE-specific logic
+
+### Flows (Debuggers)
+- [flows/startup-and-provisioning.md](./flows/startup-and-provisioning.md) — Full provisioning flow
+- [flows/package-management.md](./flows/package-management.md) — Package operations
+- [flows/system-configuration.md](./flows/system-configuration.md) — System-level config
+
+## Maintenance Metadata
+
+- **Last reviewed**: 2026-10-08
+- **Owner**: Repository maintainer
+- **Coverage status**: Comprehensive — all scripts, modules, resources, and integrations documented
+- **Source of truth**: This documentation derived from exhaustive reverse-engineering of source code

docs/ambiguities-and-open-questions.md

@@ -0,0 +1,40 @@
+# Ambiguities and Open Questions
+
+This document captures known ambiguities, open questions, and TODOs for the linux-setup-script repository.
+
+## Known Ambiguities
+
+- **Package Manager Abstraction**: The package-management abstraction layer needs clearer definition of supported package managers across distributions. Currently supports pacman, apt, apk, pkg, Flatpak, Cargo, GitHub releases, but may need additional adapters.
+
+- **Privilege Escalation Model**: The `run_as_su` function uses `sudo -n true` or `su -c 'true'` detection, but behavior differs between sudo and su implementations. Need to document exact detection logic.
+
+- **File System Constants**: Path constants in `filesystem.sh` need standardization. Some constants are defined in multiple places - need to consolidate.
+
+- **Configuration Schema**: Configuration files use different formats (INI, JSON, XML, GSettings). Need to document format precedence and validation rules.
+
+- **Android/Termux Support**: Android support appears limited to specific package managers (apk, pkg). Need to verify compatibility with other Android package managers.
+
+## Open Questions
+
+1. Should we add explicit support for Snap packages in the package management abstraction?
+2. How should we handle cross-distro configuration files (e.g., shared configs between Arch and Ubuntu)?
+3. What is the expected behavior when running on immutable distros (e.g., Silverblue, MicroOS)?
+4. Are there any edge cases with file locking during atomic writes that need special handling?
+5. Should we add more comprehensive error codes for different failure scenarios?
+
+## TODOs
+
+- [ ] Review and document privilege escalation detection logic
+- [ ] Consolidate filesystem path constants
+- [ ] Add Snap package support to package management abstraction
+- [ ] Document configuration format precedence rules
+- [ ] Verify Android/Termux compatibility with all package managers
+- [ ] Add more comprehensive error code documentation
+- [ ] Review atomic write edge cases
+
+## References
+
+- [components/filesystem.md](./components/filesystem.md)
+- [components/package-management.md](./components/package-management.md)
+- [components/configuration-management.md](./components/configuration-management.md)
+- [security.md](./security.md)

docs/api-reference/INDEX.md

@@ -0,0 +1,121 @@
+# API Reference Index
+
+This directory contains API reference documentation for the linux-setup-script
+repository.
+
+## Overview
+
+The API reference provides detailed documentation for all public interfaces,
+functions, and data structures exposed by the linux-setup-script framework.
+
+## Documentation Catalogue
+
+### Foundation Layer APIs
+
+| File | Description |
+|------|-------------|
+| [filesystem.md](./filesystem.md) | Path resolution, file operations, directory management |
+| [common.md](./common.md) | Execution primitives, privilege escalation, logging |
+| [system-info.md](./system-info.md) | Platform detection, environment variables |
+| [package-management.md](./package-management.md) | Package manager abstraction, operations |
+| [config.md](./config.md) | Configuration file manipulation |
+| [service-management.md](./service-management.md) | Service control, systemd/OpenRC |
+| [apps.md](./apps.md) | Application management, installation |
+| [github.md](./github.md) | GitHub integration, releases, CLI |
+
+### Script APIs
+
+| File | Description |
+|------|-------------|
+| [configure-system.md](./configure-system.md) | System configuration functions |
+| [configure-locale.md](./configure-locale.md) | Locale configuration |
+| [configure-time.md](./configure-time.md) | Time and timezone configuration |
+| [configure-repositories.md](./configure-repositories.md) | Repository configuration |
+| [install-packages.md](./install-packages.md) | Package installation |
+| [update-rcs.md](./update-rcs.md) | RC file deployment |
+| [update-resources.md](./update-resources.md) | Resource deployment |
+| [update-profiles.md](./update-profiles.md) | Profile script deployment |
+| [configure-launchers.md](./configure-launchers.md) | Desktop launcher modification |
+| [configure-autostart-apps.md](./configure-autostart-apps.md) | Autostart configuration |
+| [configure-default-apps.md](./configure-default-apps.md) | Default application configuration |
+| [configure-directories.md](./configure-directories.md) | Directory configuration |
+| [configure-services-system.md](./configure-services-system.md) | System service configuration |
+| [configure-services-user.md](./configure-services-user.md) | User service configuration |
+| [configure-hardware-integration.md](./configure-hardware-integration.md) | Hardware configuration |
+| [update-grub.md](./update-grub.md) | GRUB configuration |
+| [configure-permissions.md](./configure-permissions.md) | Permission management |
+
+## Usage Patterns
+
+### Foundation Layer Usage
+
+```bash
+# Source foundation modules
+source "${REPO_DIR}/scripts/common/filesystem.sh"
+source "${REPO_DIR}/scripts/common/common.sh"
+source "${REPO_DIR}/scripts/common/system-info.sh"
+source "${REPO_DIR}/scripts/common/package-management.sh"
+```
+
+### Privilege Escalation
+
+```bash
+# Run as root (via sudo/su)
+run_as_su command
+
+# Run script as root
+run_script_as_su /path/to/script.sh
+```
+
+### File Operations
+
+```bash
+# Update file if content differs
+update_file_if_distinct "${source}" "${target}"
+
+# Ensure directory exists
+ensure_directory "${dir}"
+```
+
+### Package Operations
+
+```bash
+# Install package
+install_package "package-name"
+
+# Check if package installed
+is_package_installed "package-name"
+
+# Update package manager
+call_package_manager update
+```
+
+## Data Structures
+
+### Environment Variables
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `REPO_DIR` | string | Absolute path to repository root |
+| `DISTRO_FAMILY` | string | Arch, Debian, Ubuntu, Alpine, Android |
+| `HAS_SU_PRIVILEGES` | boolean | true if can escalate to root |
+| `RUN_AS_SU` | string | Command prefix for root operations |
+| `DESKTOP_ENVIRONMENT` | string | GNOME, KDE, MATE, LXDE, Phosh |
+| `HAS_GUI` | boolean | true if graphical environment |
+| `GTK_THEME` | string | Current GTK theme name |
+| `GTK_THEME_VARIANT` | string | dark or light |
+
+## Error Handling
+
+All APIs follow consistent error handling patterns:
+
+- Return 0 on success, non-zero on failure
+- Log errors with `log_error`
+- Use `assert_*` functions for validation
+- Continue on non-critical failures
+
+## See Also
+
+- [](../architecture.md) — High-level architecture
+- [](../flows/startup-and-provisioning.md) — Main execution flow
+- [](../components/foundation-layer.md) — Foundation layer details