autospan 0.1.0__tar.gz

autospan-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+Install the development dependencies and run the checks in
+[the development guide](docs/DEVELOPING.md).
+
+Keep the core independent of protocols, vendors and projects. Driver implementations
+and project configuration belong in separate packages. Add a provider contract only
+when real tool substitution requires it and its semantics can stay generic; see
+[the design principles](docs/DESIGN.md).
+
+Include tests for behavior changes and update the relevant public docs. Use synthetic
+fixtures and contribute only material you have the right to license under MIT.
+Keep private configuration, credentials and generated evidence out of commits.

autospan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nidhal Abidi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

autospan-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include CONTRIBUTING.md SECURITY.md RELEASING.md
+recursive-include docs *.md
+recursive-include tests *.py
+recursive-include scripts *.py
+global-exclude __pycache__ *.py[cod]
+prune artifacts
+prune .github

autospan-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: autospan
+Version: 0.1.0
+Summary: Test automation from hardware to CI
+Author: Nidhal Abidi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nidops/autospan
+Project-URL: Documentation, https://github.com/nidops/autospan/blob/master/docs/ARCHITECTURE.md
+Project-URL: Source, https://github.com/nidops/autospan
+Project-URL: Issues, https://github.com/nidops/autospan/issues
+Keywords: testing,test-automation,hardware,pytest,ci,embedded
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6.0
+Provides-Extra: tui
+Requires-Dist: textual>=0.80; extra == "tui"
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: textual>=0.80; extra == "dev"
+Requires-Dist: ruff>=0.12; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine<8,>=6.2; extra == "dev"
+Requires-Dist: packaging>=24; extra == "dev"
+Requires-Dist: readme-renderer[md]>=44; extra == "dev"
+Dynamic: license-file
+
+# AutoSpan
+
+Test automation from hardware to CI.
+
+AutoSpan plans and runs host-side tests with explicit resource ownership, predictable
+cleanup and evidence. Project plugins supply the configuration, drivers, scenarios
+and commands for a bench. The core stays independent of protocols, vendors and projects.
+
+```text
+configuration -> project plugin -> runtime plan -> components
+                                                   |
+                                      scenarios / console / Python
+                                                   |
+                                            events and artifacts
+```
+
+## Quick start
+
+Python 3.11 or newer is required. The package is `autospan`; use the `test` and
+`tui` extras for pytest and Textual. Install from this checkout and create a small
+project with an installed smoke scenario:
+
+These commands use a POSIX shell. On Windows, create the environment with
+`python -m venv .venv` and activate it with `.venv\Scripts\Activate.ps1` in PowerShell.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[test,tui]'
+autospan new sample
+python -m pip install -e './autospan-sample[dev]'
+autospan plan --config autospan-sample/autospan.yaml
+autospan test --config autospan-sample/autospan.yaml -- -q
+autospan console --config autospan-sample/autospan.yaml --plain --exec "sample status"
+```
+
+Interactive Textual use requires the `tui` extra and a TTY; the quick start above
+runs in batch mode.
+
+Planning validates configuration, dependencies and claims without opening hardware.
+The sample uses no hardware. For a hardware project, enable the gate explicitly:
+
+```bash
+autospan test --config bench.local.yaml -- --hardware -q
+autospan console --config bench.local.yaml --hardware
+```
+
+For `test`, arguments after `--` go to pytest. Console and contributed frontends
+accept their gate options before `--`. Installing a plugin does not activate it;
+its name must appear in the configuration.
+
+## What the runtime owns
+
+- Immutable plans, dependency ordering and resource-claim validation.
+- Component startup, rollback after partial failure and reverse-order teardown.
+- One runtime model shared by hosted pytest, the console and Python frontends.
+- Hardware and destructive gates, with optional project gates.
+- Generic periodic tasks with leases, startup checks and failure reporting.
+- Structured evidence and opaque files with correlation, size and SHA-256 metadata.
+
+Plugins use the public `autospan.api` package. `autospan._core` is internal.
+Extensions are trusted Python code; the host is not a sandbox or a real-time scheduler.
+
+## Extension points
+
+A project plugin owns bench wiring, scenarios, commands and simulation policy:
+
+```toml
+[project.entry-points."autospan.plugins"]
+my-project = "my_project.plugin:PLUGIN"
+```
+
+Plugins declare API version `1`. Their component factories open ordinary driver
+libraries and return project facades. Drivers do not need an AutoSpan entry point.
+
+Swappable tools such as flashers and debuggers use a separate provider group:
+
+```toml
+[project.entry-points."autospan.providers"]
+my-flasher = "my_flasher.autospan:PROVIDER"
+```
+
+A plan selects a provider by name through `provider_component(...)`. Discovery is
+lazy: `autospan plugins` and `autospan providers` list installed extensions without
+importing them.
+
+Commands use `CommandContext` for the live runtime, explicit output and cooperative
+cancellation. The optional `tui` extra supplies history, completion, a command
+picker and log search/export; Quit waits for the active operation. See the
+[console manual](https://github.com/nidops/autospan/blob/master/docs/CONSOLE.md).
+
+## Evidence
+
+Runs write `events.jsonl` and `manifest.json` under `artifacts/evidence/<run-id>/`.
+Use evidence steps for meaningful actions. Keep high-rate traffic in its recorder
+and attach the resulting file. Worker context must be bound explicitly and must
+match the lifetime of the work being recorded.
+
+## Documentation
+
+- [Architecture](https://github.com/nidops/autospan/blob/master/docs/ARCHITECTURE.md) and [design principles](https://github.com/nidops/autospan/blob/master/docs/DESIGN.md).
+- [Plugin authoring](https://github.com/nidops/autospan/blob/master/docs/PLUGIN_AUTHORING.md) and [scenario authoring](https://github.com/nidops/autospan/blob/master/docs/SCENARIO_MANUAL.md).
+- [Configuration](https://github.com/nidops/autospan/blob/master/docs/CONFIGURATION.md), [console](https://github.com/nidops/autospan/blob/master/docs/CONSOLE.md) and [evidence](https://github.com/nidops/autospan/blob/master/docs/EVIDENCE.md).
+- [Development](https://github.com/nidops/autospan/blob/master/docs/DEVELOPING.md) and [releasing](https://github.com/nidops/autospan/blob/master/RELEASING.md).
+- [Extension trust](https://github.com/nidops/autospan/blob/master/docs/PLUGIN_TRUST.md) and [security](https://github.com/nidops/autospan/blob/master/SECURITY.md).
+
+MIT. See [LICENSE](https://github.com/nidops/autospan/blob/master/LICENSE).

autospan-0.1.0/README.md

@@ -0,0 +1,107 @@
+# AutoSpan
+
+Test automation from hardware to CI.
+
+AutoSpan plans and runs host-side tests with explicit resource ownership, predictable
+cleanup and evidence. Project plugins supply the configuration, drivers, scenarios
+and commands for a bench. The core stays independent of protocols, vendors and projects.
+
+```text
+configuration -> project plugin -> runtime plan -> components
+                                                   |
+                                      scenarios / console / Python
+                                                   |
+                                            events and artifacts
+```
+
+## Quick start
+
+Python 3.11 or newer is required. The package is `autospan`; use the `test` and
+`tui` extras for pytest and Textual. Install from this checkout and create a small
+project with an installed smoke scenario:
+
+These commands use a POSIX shell. On Windows, create the environment with
+`python -m venv .venv` and activate it with `.venv\Scripts\Activate.ps1` in PowerShell.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[test,tui]'
+autospan new sample
+python -m pip install -e './autospan-sample[dev]'
+autospan plan --config autospan-sample/autospan.yaml
+autospan test --config autospan-sample/autospan.yaml -- -q
+autospan console --config autospan-sample/autospan.yaml --plain --exec "sample status"
+```
+
+Interactive Textual use requires the `tui` extra and a TTY; the quick start above
+runs in batch mode.
+
+Planning validates configuration, dependencies and claims without opening hardware.
+The sample uses no hardware. For a hardware project, enable the gate explicitly:
+
+```bash
+autospan test --config bench.local.yaml -- --hardware -q
+autospan console --config bench.local.yaml --hardware
+```
+
+For `test`, arguments after `--` go to pytest. Console and contributed frontends
+accept their gate options before `--`. Installing a plugin does not activate it;
+its name must appear in the configuration.
+
+## What the runtime owns
+
+- Immutable plans, dependency ordering and resource-claim validation.
+- Component startup, rollback after partial failure and reverse-order teardown.
+- One runtime model shared by hosted pytest, the console and Python frontends.
+- Hardware and destructive gates, with optional project gates.
+- Generic periodic tasks with leases, startup checks and failure reporting.
+- Structured evidence and opaque files with correlation, size and SHA-256 metadata.
+
+Plugins use the public `autospan.api` package. `autospan._core` is internal.
+Extensions are trusted Python code; the host is not a sandbox or a real-time scheduler.
+
+## Extension points
+
+A project plugin owns bench wiring, scenarios, commands and simulation policy:
+
+```toml
+[project.entry-points."autospan.plugins"]
+my-project = "my_project.plugin:PLUGIN"
+```
+
+Plugins declare API version `1`. Their component factories open ordinary driver
+libraries and return project facades. Drivers do not need an AutoSpan entry point.
+
+Swappable tools such as flashers and debuggers use a separate provider group:
+
+```toml
+[project.entry-points."autospan.providers"]
+my-flasher = "my_flasher.autospan:PROVIDER"
+```
+
+A plan selects a provider by name through `provider_component(...)`. Discovery is
+lazy: `autospan plugins` and `autospan providers` list installed extensions without
+importing them.
+
+Commands use `CommandContext` for the live runtime, explicit output and cooperative
+cancellation. The optional `tui` extra supplies history, completion, a command
+picker and log search/export; Quit waits for the active operation. See the
+[console manual](https://github.com/nidops/autospan/blob/master/docs/CONSOLE.md).
+
+## Evidence
+
+Runs write `events.jsonl` and `manifest.json` under `artifacts/evidence/<run-id>/`.
+Use evidence steps for meaningful actions. Keep high-rate traffic in its recorder
+and attach the resulting file. Worker context must be bound explicitly and must
+match the lifetime of the work being recorded.
+
+## Documentation
+
+- [Architecture](https://github.com/nidops/autospan/blob/master/docs/ARCHITECTURE.md) and [design principles](https://github.com/nidops/autospan/blob/master/docs/DESIGN.md).
+- [Plugin authoring](https://github.com/nidops/autospan/blob/master/docs/PLUGIN_AUTHORING.md) and [scenario authoring](https://github.com/nidops/autospan/blob/master/docs/SCENARIO_MANUAL.md).
+- [Configuration](https://github.com/nidops/autospan/blob/master/docs/CONFIGURATION.md), [console](https://github.com/nidops/autospan/blob/master/docs/CONSOLE.md) and [evidence](https://github.com/nidops/autospan/blob/master/docs/EVIDENCE.md).
+- [Development](https://github.com/nidops/autospan/blob/master/docs/DEVELOPING.md) and [releasing](https://github.com/nidops/autospan/blob/master/RELEASING.md).
+- [Extension trust](https://github.com/nidops/autospan/blob/master/docs/PLUGIN_TRUST.md) and [security](https://github.com/nidops/autospan/blob/master/SECURITY.md).
+
+MIT. See [LICENSE](https://github.com/nidops/autospan/blob/master/LICENSE).

autospan-0.1.0/RELEASING.md

@@ -0,0 +1,31 @@
+# Releasing AutoSpan
+
+Package version lives in `pyproject.toml`; `autospan.__version__` reads installed
+metadata. The plugin API version is separate and is currently `1`.
+
+## Setup
+
+Configure [trusted publishing](https://docs.pypi.org/trusted-publishers/)
+separately on TestPyPI and PyPI for project `autospan`, repository
+`nidops/autospan`, and workflow `publish.yml`. Use GitHub environments `testpypi`
+and `pypi` respectively, restricted to release tags, with production approval
+where available. For a new project, register a pending publisher; this does not
+reserve the package name. Confirm account ownership and public documentation links.
+
+## Release
+
+1. Update the package version and documentation.
+2. Run the [development checks](docs/DEVELOPING.md#checks) and
+   [distribution checks](docs/DEVELOPING.md#distribution-checks).
+3. From a clean checkout, tag the reviewed `master` commit as `vX.Y.Z` after all
+   supported CI jobs pass. Verify the version with
+   `python scripts/check_dist.py dist --tag vX.Y.Z`, substituting the actual version.
+4. Push the tag, then manually run **Publish** in GitHub Actions with that tag selected.
+
+The workflow reruns CI, uploads verified artifacts to TestPyPI, checks the downloaded
+wheel's hash and installation, then publishes the same artifacts to PyPI and verifies
+again. Pushes alone do not publish. Check the package page after completion.
+
+If publication fails, rerun failed jobs in the same run while its `release-dist`
+artifact is available. Never overwrite tags or uploaded files, or hide mismatches
+with `skip-existing`. Changed release contents require a new version.

autospan-0.1.0/SECURITY.md

@@ -0,0 +1,11 @@
+# Security policy
+
+Report vulnerabilities privately to the maintainers (use the repository's private
+security advisory feature); do not open a public issue.
+
+AutoSpan plugins are trusted Python code and are not sandboxed (see
+`docs/PLUGIN_TRUST.md`). Reports about a malicious or compromised plugin are out
+of scope; reports about the kernel itself (path handling in the evidence store,
+configuration parsing, plan validation, gate bypass) are in scope.
+
+Supported versions: the latest `0.x` release.

autospan-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,166 @@
+# AutoSpan architecture
+
+## Ownership
+
+> AutoSpan owns execution. A project plugin owns project meaning. Drivers are plain libraries. Swappable external tools are providers of narrow kernel contracts.
+
+## Runtime model
+
+There is one owner per opened runtime. `RuntimeSession` is the internal lifecycle
+owner; `Runtime` is its public live view. Within one Python process, active
+sessions reserve the plan's exclusive/shared resource claims atomically before
+hardware opens, and release claims after teardown or failed startup. This prevents
+function- and session-scoped fixtures from opening the same exclusively claimed
+hardware simultaneously. The registry does **not** coordinate separate processes,
+and different selector aliases still require a common canonical claim identity.
+Shared claims may coexist across sessions, but handover requires all other sessions
+claiming that resource to close first. While an external tool owns it, new claims
+are rejected until reacquisition finishes, including recovery after a failure.
+A project "workspace" is only a directory containing project files/configuration,
+never a second runtime layer. There is no separate `autospan-core` or
+`autospan-workspace` runtime product.
+
+```text
+config
+  ↓
+explicitly selected project plugin(s)
+  ↓
+declaration-only registration
+  ↓
+side-effect-free RuntimePlan
+  ↓
+provider resolution + DAG / claims validation
+  ↓
+dependency-first component acquisition
+  ↓
+one Runtime view
+  ├── pytest
+  ├── console
+  └── Python/frontends
+  │
+  ├── runtime-owned periodic scheduler
+  └── shared evidence sink
+  ↓
+stop periodic workers
+  ↓
+reverse-order component teardown
+```
+
+Merely installing a project plugin or provider never activates it.
+
+Console modes share one dispatcher and the same session:
+
+```text
+plain / batch / Textual -> CommandShell -> CommandContext.runtime -> live components
+                               |                |
+                        verdict-aware step   explicit output / cancellation
+                               |
+                     finish/join command -> stop periodic workers -> teardown
+```
+
+Textual runs one command worker and renders a bounded output queue on its UI
+thread. Busy submissions are rejected. A stop request never substitutes for
+joining that worker before the existing runtime closes.
+
+## Package boundary
+
+The `autospan` wheel contains orchestration, generic contracts and frontends.
+Protocol/device drivers are separate libraries imported by project packages.
+
+The kernel may define a narrow contract for a swappable project-level tool such as a flasher or debugger. Implementations are separate provider packages advertised through `autospan.providers`.
+
+## Project composition
+
+A project plugin normally plans one project/bench component. Its factory opens the driver libraries it needs inside an `ExitStack` and returns a project facade/rig:
+
+```text
+project plugin -> compile plan -> project component -> open drivers -> project rig
+```
+
+Do not explode every driver/client into a kernel component merely because `RuntimePlan` exists. Use separate components when independent lifecycle/dependency/resource ownership actually requires it.
+
+## Extension categories
+
+AutoSpan has two framework-level extension categories:
+
+1. **Project plugin** (`autospan.plugins`) — configuration compilation, project component factories, scenarios, commands, gates, frontends and simulation policy.
+2. **Provider** (`autospan.providers`) — one implementation of a narrow kernel contract such as `flasher` or `debugger`.
+
+Drivers use normal Python imports. They have no AutoSpan entry point, project config section or plugin dependency declaration.
+
+## Periodic execution
+
+Generic recurring execution belongs to the runtime; protocol meaning does not.
+Projects create named periodic tasks from `context.periodic` or `runtime.periodic`.
+Tasks use monotonic scheduling, nested leases, deterministic shutdown, failure
+propagation and basic timing statistics. A lease can optionally wait for one successful
+first callback (`startup_timeout_s`) when a project needs a generic readiness boundary.
+AutoSpan never knows whether the callback is network management, a diagnostic keep-alive,
+serial polling or something else.
+
+Periodic workers are stopped before component teardown so a worker cannot continue
+using a driver after its resource has closed. This is host-side orchestration, not a
+hard-real-time scheduler.
+Callbacks must return for shutdown to finish. A slow-stop deadline reports failure;
+the owner still waits for the worker instead of closing its resources underneath it.
+This is intentionally **not** a hard shutdown timeout: Python cannot safely kill a
+blocked thread and revoke its driver's handles. Every periodic callback must use
+finite I/O timeouts and honor its driver's cooperative cancellation policy. If a
+strict stop deadline is required, run the blocking work in a supervised process
+with an explicit termination and ownership-recovery contract.
+
+## Evidence
+
+Control-plane events are small and structured. High-rate data stays in the owning
+driver/project recorder and is committed as an opaque artifact. Artifact formats are
+open-ended; the evidence store records metadata, correlation, completeness, size and
+hash without parsing the traffic format.
+
+## Lifecycle
+
+Every component is acquired through a context manager. AutoSpan uses dependency order for startup and reverse order for cleanup. Partial startup failures roll back already-opened components.
+
+Runtime entry validates resource claims before reserving resources or opening
+components, including for directly constructed plans. Shutdown rejects new
+handovers, stops and joins periodic workers, then waits for admitted handovers
+to finish reacquisition and diagnostics before closing components. Reservations
+remain held until component cleanup has been attempted, including after errors.
+The session can be entered again once cleanup finishes.
+
+Shutdown from inside the session's own handover or periodic callback is rejected
+to avoid waiting on the caller itself. Drivers, handover bodies and evidence
+callbacks must return for cleanup to finish; a blocked hardware call cannot be
+safely cancelled by closing its resources from another thread.
+
+## Pytest
+
+AutoSpan invokes pytest with explicitly contributed scenario paths and one bridge plugin. Third-party pytest-plugin autoloading is disabled for hosted runs.
+
+The function-scoped `runtime` fixture acquires per test for hardware isolation.
+The explicit `session_runtime` fixture acquires once for a shared bench. Use one
+allocation scope per bench; both fixtures use the same owner model.
+
+## Gates
+
+The host always knows `hardware` and `destructive` (`destructive` implies `hardware`). Project plugins may contribute more. Gates are enforced both on scenarios and on component acquisition, before a gated factory can touch hardware.
+
+## Frontends
+
+`autospan run NAME` executes a project-contributed frontend using the same plan/runtime owner. A frontend must not create a parallel hardware lifecycle.
+
+## Outcome
+
+Function-scoped teardown sees the setup/call verdict known at that point; its own
+teardown report arrives later. The session runtime closes after all fixture reports
+and receives the aggregate outcome, including setup and teardown failures. The
+run manifest records the final pytest status. Factories can retain failure-only
+artifacts using `ComponentContext.outcome`.
+
+## Non-goals
+
+- no runtime Git/package fetching;
+- no plugin dependency graph for drivers;
+- no distributed executor;
+- no hard-real-time guarantee (including periodic workers);
+- no universal transport or device hierarchy;
+- no protocol semantics in the kernel.

autospan-0.1.0/docs/CONFIGURATION.md

@@ -0,0 +1,53 @@
+# Configuration
+
+AutoSpan owns only the host section. Each selected project plugin owns and strictly validates its own section.
+
+```yaml
+autospan:
+  plugins: [my-project]
+
+my-project:
+  port: sim
+```
+
+`autospan` currently accepts only `plugins` and `pytest`. Unknown host keys are errors. Project sections are validated by their owning project package; unknown project keys should likewise fail rather than silently default.
+
+Project plugins are loaded only when explicitly named. Installing a driver, provider or another project package does not activate it.
+
+## Command-line overrides
+
+Every config-aware command accepts repeatable `--set dotted.key=value`. Values are parsed as YAML and applied before project loading:
+
+```bash
+autospan test --config bench.yaml --set my-project.bench_config=C:/benches/b12.yaml
+autospan plan --config bench.yaml --set autospan.plugins=[my-project]
+```
+
+## Hosted pytest settings
+
+`autospan test` never reads an arbitrary project `pytest.ini`/`pyproject.toml`. It writes one `pytest.ini` per run from:
+
+1. AutoSpan defaults;
+2. `ScenarioContribution.pytest_ini` defaults from selected projects;
+3. operator `autospan.pytest.ini` overrides.
+
+Extra pytest plugins must be explicit because autoload is disabled:
+
+```yaml
+autospan:
+  plugins: [my-project]
+  pytest:
+    plugins: [pytest_metadata.plugin]
+    ini:
+      log_cli_level: DEBUG
+```
+
+`cache_dir`, `testpaths`, `rootdir` and `confcutdir` are owned by AutoSpan.
+
+Planning is side-effect free. Invalid component dependencies, cycles, resource collisions, missing providers, unknown component types and malformed configuration must fail before hardware opens.
+
+Relative project paths should be resolved against `PlanBuilder.config_dir`, the directory containing the selected AutoSpan config file.
+
+Keep machine-specific settings in ignored files such as `bench.local.yaml`.
+For credentials, store an environment-variable name in reviewed config and resolve
+its value at runtime in project code.