Update documentation: comprehensive coverage of plugins, configuration, and regression

[Copilot]

Documentation was outdated and lacked critical coverage of plugin types, configuration hierarchy, and parallel regression execution.

Changes

Quick Start (docs/home/quickstart.md)

• Prerequisites: Python 3.12+, package manager requirements
• Installation methods: uv (recommended), pipx, pip
• Basic commands with examples (git, config, regression, plugins)
• Global options reference

Plugin User Guide (docs/user-guide/plugins.md)

• Python plugins: Run in-process, access from socx import settings, full namespace access
• Script plugins: Run as subprocess via sh, no SoCX internals, any executable
• Creation guides for both types with comparison table

Example Python plugin:

plugins:
  - name: my-tool
    command: "my_package.tools:cli"  # imports and runs in-process
    help: "Tool with SoCX configuration access"

Example script plugin:

plugins:
  - name: build
    script: "./scripts/build.sh"  # spawns subprocess
    help: "Build wrapper"

Configuration User Guide (docs/user-guide/configuration.md)

• Precedence: package defaults < user config < repo config < env vars
• Configuration sources: ~/.config/socx/socx.yaml, .socx.yaml, SOCX_* env vars
• Common tasks: CLI behavior, Git manifest, regression settings, plugin management
• Advanced: Jinja2 templates, custom converters (@path, @symbol, @command)

Regression User Guide (docs/user-guide/regression.md)

• Parallel execution: max_runs_in_parallel configuration (default: 10)
• Performance tuning by workload type (CPU-bound: cores, I/O-bound: 2-3x cores)
• TUI keyboard shortcuts and configuration reference
• Troubleshooting common issues

Configuration Reference (docs/reference/configuration.md) - NEW

• Complete reference organized by sections: CLI, Git, Regression, Plugin, Convert, Language
• Field documentation with types, defaults, descriptions
• Environment variable mappings (e.g., SOCX_REGRESSION__MAX_RUNS_IN_PARALLEL)
• Configuration directives and tuning guidelines

Navigation (mkdocs.yml)

• Added Configuration Reference to nav
• Fixed typo: Conepts → Concepts

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• astral.sh
  • Triggering command: /usr/bin/curl curl -LsSf REDACTED (dns block)
• docs.python.org
  • Triggering command: /usr/bin/python3 python3 -m mkdocs build --strict (dns block)
  • Triggering command: /usr/bin/python3 python3 -m mkdocs build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Update documentation</issue_title>
<issue_description>Most of the current documentation is outdated and/or was generated and added by LLMs without a review (cuz im lazy and needed some docs)

Documentation needs to be updated with an effort to cover the following critical topics:

• A quickstart section covering prerequisites, installation, and basic commands
• A plugin user guide covering how to add python and script plugins and the differences between the 2 (a script plugin must be executable and is run as a subprocess, python plugins are run in-process and have the entire global and local namespace of socx-cli available which includes current runtime configuration values and other utilities)
• A configurations user guide briefly covering configuration options and how behaviour can be modified
• A regression user guide for running tests/regressions in parallel and configuration options for changing behaviour
• A configuration reference page documenting all of the default configurations, split by sections (i.e. git, regression, cli, etc.)</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Update documentation #108

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.