pubrun 0.1.1__tar.gz

pubrun-0.1.1/.gitignore

@@ -0,0 +1,56 @@
+# These are some examples of commonly ignored file patterns.
+# You should customize this list as applicable to your project.
+# Learn more about .gitignore:
+#     https://www.atlassian.com/git/tutorials/saving-changes/gitignore
+
+# Node artifact files
+node_modules/
+dist/
+tmp/
+runs/
+__pycache__/
+*.pyc
+p3*/
+
+# Compiled Java class files
+*.class
+
+# Compiled Python bytecode
+*.py[cod]
+.pytest_cache/
+
+# Log files
+*.log
+
+# Package files
+*.jar
+
+# Maven
+target/
+dist/
+
+# JetBrains IDE
+.idea/
+
+# Unit test reports
+TEST*.xml
+
+# Generated by MacOS
+.DS_Store
+
+# Generated by Windows
+Thumbs.db
+
+# Applications
+*.app
+*.exe
+*.war
+
+# Large media files
+*.mp4
+*.tiff
+*.avi
+*.flv
+*.mov
+*.wmv
+

pubrun-0.1.1/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.1] - 2026-05-09
+
+### Added
+
+- **`--version` CLI flag**: `pubrun --version` now prints the installed version.
+- **`PUBRUN_PROFILE` environment variable**: Overrides `[core].profile` at runtime without a config file.
+- **`__all__` declaration**: `__init__.py` now declares a formal public API surface.
+- **Console tee documentation**: README Quick Start now documents the stdout/stderr tee behavior and how to disable it for high-output scripts.
+
+### Changed
+
+- **Single-source versioning**: `__version__` is now read from installed package metadata via `importlib.metadata` instead of being hard-coded.
+- **CLI `prog` name**: Help output now shows `pubrun` instead of `__main__.py`.
+- **CLI help text**: All help strings rewritten for conciseness. Removed verbose and non-technical phrasing.
+- **Error messages**: Standardized CLI error messages to use consistent `Error: Failed to ...` format.
+- **`default.toml` comments**: Full rewrite. All configuration comments now use concise, technical phrasing.
+- **Module docstring**: `__init__.py` docstring rewritten for clarity.
+- **`CITATION.cff`**: Version bumped to 0.1.1; abstract cleaned.
+
+### Improved
+
+- **Docstring audit**: All docstrings and inline comments across 24 source files cleaned to remove non-technical prose.
+- **`_handle_inactive()` extraction**: Duplicate inactive-run handling from `annotate()` and `phase.__enter__()` consolidated into a shared helper.
+
+### Security
+
+- **Subprocess argv redaction**: CLI arguments in `sys.argv` and subprocess records matching sensitive patterns (passwords, tokens, API keys, etc.) are now redacted before being written to the manifest. Configurable via `[redaction].argv_enabled` in `.pubrun.toml`.
+- **Expanded secret detection**: Added patterns for `private`, `conn_str`, `connection_string`, `database_url`, `dsn`, `signing`, and `bearer` to the default sensitive key regex.
+- **Thread-safe subprocess tracking**: `SubprocessSpy._records` mutations are now protected by `threading.Lock` to prevent race conditions in parallelized HPC array jobs.
+
+### Fixed
+
+- **Double-finalization guard**: `_finalize_state()` is now idempotent, preventing redundant cleanup calls in writer or exit hooks.
+- **Ghost mode stability**: Tracker now initializes `_outcome` and `_finalized` attributes even on failure (e.g., read-only filesystem), preventing `AttributeError` on `stop()`.
+- **Event stream race condition**: Consolidated double-lock into a single atomic lock covering both budget check and file I/O.
+- **Config merge leakage**: `_deep_merge()` now uses `copy.deepcopy()` to prevent nested dictionary reference sharing across run instances.
+- **Diagnostics field names**: Subprocess reports now use `argv`/`exit_code` to match the actual manifest schema (was `command`/`return_code`).
+- **Mutable default argument**: Fixed `get_invocation(config: Dict = {})` to `Optional[Dict] = None`.
+- **OS detection**: Methods report now uses `host.os_name` from the manifest instead of the Windows-only `OS` environment variable.
+- **Import-time safety**: Boot sequence wrapped in `try/except` to prevent corrupt configs from crashing `import pubrun`.
+- **shlex fallback**: `SubprocessSpy` now handles unterminated quotes in command strings without crashing.
+
+### Improved
+
+- **Console performance**: `TqdmSafeTee.write()` rewritten from O(n²) char-by-char to O(n) split-based processing.
+- **File hashing**: SHA-256 generation uses chunked 8KB reads instead of full-file read, preventing memory spikes on large inputs.
+- **Redaction configurability**: Env var and argv redaction are independently toggleable via `[redaction].env_enabled` and `[redaction].argv_enabled`. Both default to on.
+- **Git safety**: `_run_git()` calls wrapped in `disable_spy()` to prevent circular subprocess logging.
+
+### Removed
+
+- 224 redundant `pass # for auto-indentation` statements across 18 source files.
+
+### Tests
+
+- Test suite expanded from 13 to 232 tests across 12 test files.
+- New coverage: manifest schema contract, all 6 capture engines, public API contracts (start/stop/annotate/phase/tracked_run/audit_run/diff), config file discovery and precedence, diff normalization and PATH splitting, report generation (markdown/LaTeX), manifest hydration, and exhaustive CLI dispatch for every subcommand.
+- Added `tests/fixtures/sample_manifest.json` golden fixture for deterministic contract tests.
+
+## [0.1.0] - 2026-04-03
+
+### Added
+
+- **Core library**: Singleton `Run` tracker with automatic provenance capture via `start()`, `stop()`, `annotate()`, `phase()`, `tracked_run()`, `audit_run()`, and `diff()`.
+- **Manifest-first design**: Each run produces a `manifest.json` (schema v1.0), `config.resolved.json`, and optional `events.jsonl`, console logs, and `methods.md`/`.tex`.
+- **Capture engines**: Modular sub-engines for hardware, environment, packages, git, invocation, subprocesses, console (tee-style with tqdm-safe carriage return squashing), resources (background thread sampling), and process metadata.
+- **Configuration system**: Hierarchical TOML configuration (`default.toml` -> user-global -> project-local -> API overrides) with per-category depth controls (`off`, `basic`, `standard`, `deep`).
+- **Redaction engine**: Regex-based detection and destructive redaction of sensitive environment variables.
+- **CLI commands**: `pubrun report`, `pubrun methods`, `pubrun rerun`, `pubrun diff`, `pubrun meta`, `pubrun cite`.
+- **CLI utilities**: `--create-config`, `--show-config`, `--info`, `--run-tests`.
+- **HPC support**: Parent-child manifest hydration via `PUBRUN_META_REF` for array job provenance.
+- **Ghost mode**: Silent failure if filesystem operations fail, preventing the library from crashing the host application.
+- **Subprocess spy**: Transparent monkey-patching of `subprocess.Popen` and `os.system` to capture spawned processes.
+- **Schema**: Formal JSON Schema (`schemas/manifest.schema.json`) for manifest validation.
+- **Documentation**: Architecture spec, functional spec, CLI reference, API reference.
+- **Test suite**: pytest-based tests covering tracker lifecycle, config resolution, event streaming, hardware capture, resource monitoring, subprocess interception, and console tee.
+
+### Design Decisions
+
+- **Timestamps as POSIX epoch floats**: All timestamps use `time.time()` for sub-second precision, timezone-agnostic storage, trivial arithmetic, and deterministic serialization.
+- **Zero dependencies**: No runtime dependencies except `tomli` for Python < 3.11.
+- **Auto-start**: Configurable import-time activation via `auto_start = true` in config.
+
+### Notes
+
+- Tests require `pytest >= 7.0` for `pythonpath` support in `pyproject.toml`.
+- `tox.ini` targets Python 3.10 and 3.11.

pubrun-0.1.1/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use this software in your research, please cite it."
+authors:
+  - family-names: "Fariello"
+    given-names: "Gabriele"
+    orcid: "https://orcid.org/0000-0002-0326-4752"
+title: "pubrun: Lightweight native execution provenance and reproducibility tracking"
+version: 0.1.1
+date-released: 2026-04-03
+url: "https://github.com/gfariello/pubrun"
+repository-code: "https://github.com/gfariello/pubrun"
+abstract: >-
+  pubrun is a zero-dependency, manifest-first Python framework for tracking
+  computational provenance, environment state, and execution metadata without
+  requiring complex virtualization overhead.
+keywords:
+  - reproducibility
+  - provenance
+  - metadata
+  - research-software
+license: "BSD-3-Clause"

pubrun-0.1.1/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2007-2026 Gabriele Fariello
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pubrun-0.1.1/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: pubrun
+Version: 0.1.1
+Summary: A lightweight Python library for capturing execution context.
+Project-URL: Homepage, https://github.com/gfariello/pubrun
+Project-URL: Repository, https://github.com/gfariello/pubrun
+Project-URL: Issues, https://github.com/gfariello/pubrun/issues
+Author: Gabriele Fariello
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: execution-tracking,metadata,provenance,reproducibility,research-software,telemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: tomli>=1.1.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: tox>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[README](README.md) | [Architecture](docs/architecture.md) | [Functional Spec](docs/functional_spec.md) | [API](docs/api.md) | [CLI](docs/cli.md) | [Configuration](docs/configuration.md) | [Manifest](docs/manifest.md)
+
+# pubrun
+
+> **Let your code monitor itself and write its own Methods section while you go to the pub.**
+
+`pubrun` is a stupidly simple, zero-dependency Python library that eliminates the boilerplate of documenting methodology, tracking versions, recording inputs, and monitoring resources — making it dramatically easier to publish, share, and reproduce your models and research. If you're feeling formal, you can think of "publication-ready runner" as the meaning of the name.
+
+## Quick Start
+
+```python
+import pubrun  # That's it 90% of the time!
+```
+or
+```bash
+pubrun -h  # Lots of info here.
+```
+That's it. No frameworks, no heavy integrations, no syntax hijacking.
+When the script exits, `pubrun` silently generates a structured, lightweight footprint in your local `./runs/` directory.
+
+> [!NOTE]
+> **Console capture**: By default, `pubrun` tees `stdout` and `stderr` to log files in the run directory. Your terminal output is unchanged, but a copy is saved alongside the manifest. If your script produces very high output volume, you can disable this with `capture_mode = "off"` in `.pubrun.toml` or via `pubrun.start(console={"capture_mode": "off"})`. See [Configuration](docs/configuration.md) for details.
+
+See [CLI Reference](docs/cli.md) and [API Reference](docs/api.md) for full details.
+
+## Features
+
+- **Automatic Execution Tracing** — Captures environment variables, hardware specs, and dependency graphs without manual configuration.
+- **Publication-Ready Output** — Generates LaTeX/Markdown methodology blocks ready for academic papers.
+- **Semantic Diffing** — Compares execution footprints to identify subtle but critical differences between runs.
+- **Secret Redaction** — Automatically detects and redacts passwords, tokens, and API keys in environment variables and CLI arguments.
+- **Codebase Drift Detection** — Compares current code state against the execution snapshot to highlight changes.
+- **Cross-Platform Reproducibility** — Extracts initialization commands for seamless environment replication.
+- **HPC Optimized** — Supports global parent-child manifest hydration to minimize overhead on massive clusters.
+
+## The Problem
+
+Modern scientific workflows rely on implicit state. When it's time to publish a paper or ship a model, researchers are forced to retroactively piece together their methodology — PyTorch versions, OS constraints, hardware parameters — from memory.
+
+## The Solution
+
+`pubrun` permanently ends this friction.
+
+With a single `import pubrun`, the library quietly traces your script execution, hashes your environment dependencies, detects codebase drift, and compiles publication-ready **Computational Methodology** LaTeX/Markdown blocks so your run is instantly citable.
+
+### Lazy Initialization (Explicit Tracking)
+
+By default, simply importing `pubrun` spins up an invisible tracer. If you want to import `pubrun` without instantly generating a footprint until you explicitly call `pubrun.start()`, set this in your `.pubrun.toml`:
+
+```toml
+[core]
+auto_start = false
+```
+
+Or set the environment variable before import:
+
+```python
+import os
+os.environ["PUBRUN_AUTO_START"] = "false"
+
+import pubrun
+# No directory is generated until you say so.
+
+pubrun.start(output_dir="./custom_storage", profile="deep")
+```
+
+Now extract your method paragraph for your paper:
+
+```bash
+pubrun methods --format latex
+```
+
+### Sample Output
+
+> Computational experiments were executed on a machine running Linux (5.15.0-91-generic) equipped with an Intel(R) Core(TM) i7-12700H and 32.0 GB of RAM. The execution environment relied on Python 3.10.12 (CPython). Key dependencies tracked include torch (v2.0.1) and numpy (v1.24.3). To guarantee computational reproducibility, the exact state of the source code was anchored at Git commit `a1b2c3d4`. Environment and execution provenance were tracked using the `pubrun` library [1].
+
+> [!NOTE]
+> **Windows support**: `pubrun` works on Windows, but some capture engines have reduced functionality. Process `uid`/`gid` fields are not available, and `os.system` interception uses shell-string parsing rather than structured argument lists. All other features work identically.
+
+---
+
+## CLI Reference
+
+The `pubrun` CLI provides six commands and four diagnostic flags, all designed to work equally well on a developer laptop or across a Slurm array of thousands of HPC jobs.
+
+### `pubrun cite`
+Generates the bibliographic citation for crediting this library in your paper.
+```bash
+pubrun cite --style bibtex
+```
+
+### `pubrun methods`
+Translates raw JSON diagnostic payloads into publication-ready methodology paragraphs.
+```bash
+pubrun methods [RUN_DIR] --format markdown|latex
+```
+
+### `pubrun report`
+A diagnostic viewer that surfaces execution timing, hardware, dependencies, and codebase drift. Accepts multiple run directories for sequential evaluation.
+```bash
+pubrun report ./runs/pubrun-A ./runs/pubrun-B --deep
+```
+
+### `pubrun rerun`
+Extracts the exact shell command needed to reproduce a run.
+```bash
+pubrun rerun ./runs/pubrun-A
+```
+
+### `pubrun diff`
+Generates a semantic side-by-side comparison between two execution traces, filtering volatile noise (timestamps, PIDs) by default.
+```bash
+pubrun diff ./runs/pubrun-A ./runs/pubrun-B --same --basic --wrap
+```
+
+### `pubrun meta`
+Generates a standalone environment snapshot for HPC parent-child hydration.
+```bash
+pubrun meta --out ./runs/meta.json --deep
+```
+
+### Diagnostic Flags
+
+| Flag | Description |
+|---|---|
+| `--create-config` | Bootstrap a fully commented `.pubrun.toml` file |
+| `--show-config` | Print the default configuration to the terminal |
+| `--info` | Display system capabilities and pubrun version |
+| `--run-tests` | Execute the built-in self-test suite |
+
+See [CLI Reference](docs/cli.md) for full details and examples.
+
+---
+
+## Advanced HPC Ecosystems (Global Hydration)
+
+If you run thousands of array jobs across a cluster, you don't want each child run wasting time and disk logging identical dependency graphs. `pubrun` supports **parent-child manifest hydration**.
+
+#### Step 1: Snap the Parent Cluster
+On the head node, snapshot the global environment:
+```bash
+pubrun meta --out ./runs/meta.json --deep
+```
+This generates a deep metadata map of hardware, environment variables, and the full Python package tree.
+
+#### Step 2: Hydrate Children
+In your Slurm script, reference the parent snapshot:
+```bash
+export PUBRUN_META_REF=meta.json
+python minimal_script.py
+```
+
+Child scripts automatically skip heavy footprint tracking. When you run `pubrun report` or `pubrun methods`, the orchestrator detects the `PUBRUN_META_REF`, pulls in the parent `meta.json` context, and stitches the complete hardware and dependency picture back together. It also compares script timestamps against the parent snapshot and warns you if **environmental drift** has been detected.
+
+---
+
+## Configuration
+
+`pubrun` supports a hierarchical configuration system (highest to lowest precedence):
+
+1. **API overrides** — `pubrun.start(profile="deep")`
+2. **Environment variables** — `PUBRUN_AUTO_START=false`
+3. **Local project config** — `.pubrun.toml` or `.config/pubrun/config.toml`
+4. **User home config** — `~/.config/pubrun/config.toml`
+5. **Built-in defaults** — `default.toml` (shipped with the library)
+
+### Generate a Configuration File
+```bash
+pubrun --create-config
+```
+
+See [Configuration Reference](docs/configuration.md) for all settings and examples.
+
+---
+
+## Security & Redaction
+
+`pubrun` automatically detects and redacts sensitive values (passwords, tokens, API keys, credentials) in both environment variables and CLI arguments before writing them to the manifest. Redaction is **destructive by default** — raw values are replaced with `{"representation": "redacted"}`, and no hashes are generated, to prevent brute-force attacks.
+
+Both environment variable and argv redaction are independently configurable:
+
+```toml
+[redaction]
+env_enabled = true    # Redact matching environment variable values
+argv_enabled = true   # Redact matching CLI argument values
+```
+
+See [Configuration Reference](docs/configuration.md) for the full redaction policy and regex pattern.
+
+---
+
+## Roadmap
+
+### Pre-v0.2
+
+1. **Sphinx / MkDocs integration** — Generate hosted API documentation from docstrings.
+2. **Subprocess argv redaction refinement** — The current regex-based approach may over-match legitimate scientific arguments (e.g., `--output=secret_findings.csv`). Community input welcome on the best policy.
+3. **Coverage reporting** — Integrate `pytest-cov` into CI for coverage tracking.
+4. **Plugin / extension model** — Formal extension points for custom capture engines.
+5. **Artifact registration API** — `register_artifact()` for tracking user-produced output files.
+6. **Custom metadata API** — `register_metadata()` for injecting structured data into the manifest.
+7. **Determinism tracking** — `register_seed()` and the `[capture.determinism]` engine for recording pseudorandom seeds.
+8. **Combined console log** — Interleaved `combined.log` output alongside `stdout.log` and `stderr.log`.
+
+---
+
+## Acknowledgements
+
+`pubrun` was redesigned and rewritten from pre-existing custom libraries, code fragments, scripts, and ideas spanning almost two decades, with the assistance of Google Antigravity for its official release.
+
+## License
+
+Released under the BSD 3-Clause License. Copyright (c) 2007-2026 Gabriele Fariello. See the [LICENSE](LICENSE) file for full terms.
+
+---
+
+[README](README.md) | [Architecture](docs/architecture.md) | [Functional Spec](docs/functional_spec.md) | [API](docs/api.md) | [CLI](docs/cli.md) | [Configuration](docs/configuration.md) | [Manifest](docs/manifest.md)

pubrun-0.1.1/README.md

@@ -0,0 +1,217 @@
+[README](README.md) | [Architecture](docs/architecture.md) | [Functional Spec](docs/functional_spec.md) | [API](docs/api.md) | [CLI](docs/cli.md) | [Configuration](docs/configuration.md) | [Manifest](docs/manifest.md)
+
+# pubrun
+
+> **Let your code monitor itself and write its own Methods section while you go to the pub.**
+
+`pubrun` is a stupidly simple, zero-dependency Python library that eliminates the boilerplate of documenting methodology, tracking versions, recording inputs, and monitoring resources — making it dramatically easier to publish, share, and reproduce your models and research. If you're feeling formal, you can think of "publication-ready runner" as the meaning of the name.
+
+## Quick Start
+
+```python
+import pubrun  # That's it 90% of the time!
+```
+or
+```bash
+pubrun -h  # Lots of info here.
+```
+That's it. No frameworks, no heavy integrations, no syntax hijacking.
+When the script exits, `pubrun` silently generates a structured, lightweight footprint in your local `./runs/` directory.
+
+> [!NOTE]
+> **Console capture**: By default, `pubrun` tees `stdout` and `stderr` to log files in the run directory. Your terminal output is unchanged, but a copy is saved alongside the manifest. If your script produces very high output volume, you can disable this with `capture_mode = "off"` in `.pubrun.toml` or via `pubrun.start(console={"capture_mode": "off"})`. See [Configuration](docs/configuration.md) for details.
+
+See [CLI Reference](docs/cli.md) and [API Reference](docs/api.md) for full details.
+
+## Features
+
+- **Automatic Execution Tracing** — Captures environment variables, hardware specs, and dependency graphs without manual configuration.
+- **Publication-Ready Output** — Generates LaTeX/Markdown methodology blocks ready for academic papers.
+- **Semantic Diffing** — Compares execution footprints to identify subtle but critical differences between runs.
+- **Secret Redaction** — Automatically detects and redacts passwords, tokens, and API keys in environment variables and CLI arguments.
+- **Codebase Drift Detection** — Compares current code state against the execution snapshot to highlight changes.
+- **Cross-Platform Reproducibility** — Extracts initialization commands for seamless environment replication.
+- **HPC Optimized** — Supports global parent-child manifest hydration to minimize overhead on massive clusters.
+
+## The Problem
+
+Modern scientific workflows rely on implicit state. When it's time to publish a paper or ship a model, researchers are forced to retroactively piece together their methodology — PyTorch versions, OS constraints, hardware parameters — from memory.
+
+## The Solution
+
+`pubrun` permanently ends this friction.
+
+With a single `import pubrun`, the library quietly traces your script execution, hashes your environment dependencies, detects codebase drift, and compiles publication-ready **Computational Methodology** LaTeX/Markdown blocks so your run is instantly citable.
+
+### Lazy Initialization (Explicit Tracking)
+
+By default, simply importing `pubrun` spins up an invisible tracer. If you want to import `pubrun` without instantly generating a footprint until you explicitly call `pubrun.start()`, set this in your `.pubrun.toml`:
+
+```toml
+[core]
+auto_start = false
+```
+
+Or set the environment variable before import:
+
+```python
+import os
+os.environ["PUBRUN_AUTO_START"] = "false"
+
+import pubrun
+# No directory is generated until you say so.
+
+pubrun.start(output_dir="./custom_storage", profile="deep")
+```
+
+Now extract your method paragraph for your paper:
+
+```bash
+pubrun methods --format latex
+```
+
+### Sample Output
+
+> Computational experiments were executed on a machine running Linux (5.15.0-91-generic) equipped with an Intel(R) Core(TM) i7-12700H and 32.0 GB of RAM. The execution environment relied on Python 3.10.12 (CPython). Key dependencies tracked include torch (v2.0.1) and numpy (v1.24.3). To guarantee computational reproducibility, the exact state of the source code was anchored at Git commit `a1b2c3d4`. Environment and execution provenance were tracked using the `pubrun` library [1].
+
+> [!NOTE]
+> **Windows support**: `pubrun` works on Windows, but some capture engines have reduced functionality. Process `uid`/`gid` fields are not available, and `os.system` interception uses shell-string parsing rather than structured argument lists. All other features work identically.
+
+---
+
+## CLI Reference
+
+The `pubrun` CLI provides six commands and four diagnostic flags, all designed to work equally well on a developer laptop or across a Slurm array of thousands of HPC jobs.
+
+### `pubrun cite`
+Generates the bibliographic citation for crediting this library in your paper.
+```bash
+pubrun cite --style bibtex
+```
+
+### `pubrun methods`
+Translates raw JSON diagnostic payloads into publication-ready methodology paragraphs.
+```bash
+pubrun methods [RUN_DIR] --format markdown|latex
+```
+
+### `pubrun report`
+A diagnostic viewer that surfaces execution timing, hardware, dependencies, and codebase drift. Accepts multiple run directories for sequential evaluation.
+```bash
+pubrun report ./runs/pubrun-A ./runs/pubrun-B --deep
+```
+
+### `pubrun rerun`
+Extracts the exact shell command needed to reproduce a run.
+```bash
+pubrun rerun ./runs/pubrun-A
+```
+
+### `pubrun diff`
+Generates a semantic side-by-side comparison between two execution traces, filtering volatile noise (timestamps, PIDs) by default.
+```bash
+pubrun diff ./runs/pubrun-A ./runs/pubrun-B --same --basic --wrap
+```
+
+### `pubrun meta`
+Generates a standalone environment snapshot for HPC parent-child hydration.
+```bash
+pubrun meta --out ./runs/meta.json --deep
+```
+
+### Diagnostic Flags
+
+| Flag | Description |
+|---|---|
+| `--create-config` | Bootstrap a fully commented `.pubrun.toml` file |
+| `--show-config` | Print the default configuration to the terminal |
+| `--info` | Display system capabilities and pubrun version |
+| `--run-tests` | Execute the built-in self-test suite |
+
+See [CLI Reference](docs/cli.md) for full details and examples.
+
+---
+
+## Advanced HPC Ecosystems (Global Hydration)
+
+If you run thousands of array jobs across a cluster, you don't want each child run wasting time and disk logging identical dependency graphs. `pubrun` supports **parent-child manifest hydration**.
+
+#### Step 1: Snap the Parent Cluster
+On the head node, snapshot the global environment:
+```bash
+pubrun meta --out ./runs/meta.json --deep
+```
+This generates a deep metadata map of hardware, environment variables, and the full Python package tree.
+
+#### Step 2: Hydrate Children
+In your Slurm script, reference the parent snapshot:
+```bash
+export PUBRUN_META_REF=meta.json
+python minimal_script.py
+```
+
+Child scripts automatically skip heavy footprint tracking. When you run `pubrun report` or `pubrun methods`, the orchestrator detects the `PUBRUN_META_REF`, pulls in the parent `meta.json` context, and stitches the complete hardware and dependency picture back together. It also compares script timestamps against the parent snapshot and warns you if **environmental drift** has been detected.
+
+---
+
+## Configuration
+
+`pubrun` supports a hierarchical configuration system (highest to lowest precedence):
+
+1. **API overrides** — `pubrun.start(profile="deep")`
+2. **Environment variables** — `PUBRUN_AUTO_START=false`
+3. **Local project config** — `.pubrun.toml` or `.config/pubrun/config.toml`
+4. **User home config** — `~/.config/pubrun/config.toml`
+5. **Built-in defaults** — `default.toml` (shipped with the library)
+
+### Generate a Configuration File
+```bash
+pubrun --create-config
+```
+
+See [Configuration Reference](docs/configuration.md) for all settings and examples.
+
+---
+
+## Security & Redaction
+
+`pubrun` automatically detects and redacts sensitive values (passwords, tokens, API keys, credentials) in both environment variables and CLI arguments before writing them to the manifest. Redaction is **destructive by default** — raw values are replaced with `{"representation": "redacted"}`, and no hashes are generated, to prevent brute-force attacks.
+
+Both environment variable and argv redaction are independently configurable:
+
+```toml
+[redaction]
+env_enabled = true    # Redact matching environment variable values
+argv_enabled = true   # Redact matching CLI argument values
+```
+
+See [Configuration Reference](docs/configuration.md) for the full redaction policy and regex pattern.
+
+---
+
+## Roadmap
+
+### Pre-v0.2
+
+1. **Sphinx / MkDocs integration** — Generate hosted API documentation from docstrings.
+2. **Subprocess argv redaction refinement** — The current regex-based approach may over-match legitimate scientific arguments (e.g., `--output=secret_findings.csv`). Community input welcome on the best policy.
+3. **Coverage reporting** — Integrate `pytest-cov` into CI for coverage tracking.
+4. **Plugin / extension model** — Formal extension points for custom capture engines.
+5. **Artifact registration API** — `register_artifact()` for tracking user-produced output files.
+6. **Custom metadata API** — `register_metadata()` for injecting structured data into the manifest.
+7. **Determinism tracking** — `register_seed()` and the `[capture.determinism]` engine for recording pseudorandom seeds.
+8. **Combined console log** — Interleaved `combined.log` output alongside `stdout.log` and `stderr.log`.
+
+---
+
+## Acknowledgements
+
+`pubrun` was redesigned and rewritten from pre-existing custom libraries, code fragments, scripts, and ideas spanning almost two decades, with the assistance of Google Antigravity for its official release.
+
+## License
+
+Released under the BSD 3-Clause License. Copyright (c) 2007-2026 Gabriele Fariello. See the [LICENSE](LICENSE) file for full terms.
+
+---
+
+[README](README.md) | [Architecture](docs/architecture.md) | [Functional Spec](docs/functional_spec.md) | [API](docs/api.md) | [CLI](docs/cli.md) | [Configuration](docs/configuration.md) | [Manifest](docs/manifest.md)