@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/docs/operations/OPERATIONS.md

@@ -0,0 +1,164 @@
+# Operations
+
+Core workflows for keeping your dotfiles running across platforms.
+
+---
+
+## Platforms
+
+### macOS
+
+**Primary manager**: `Homebrew`
+
+- **Update**:
+  ```bash
+  chezmoi update
+  ```
+  This runs `brew bundle install` behind the scenes to reconcile against the declared Brewfiles.
+- **Permission issues**: `sudo chown -R $(whoami) $(brew --prefix)/*`
+- **Drift**: Run `brew bundle cleanup` to remove unmanaged packages.
+
+### Linux (Debian, Ubuntu, Kali)
+
+**Primary manager**: `apt-get` / `snap`
+
+- **Update**:
+  ```bash
+  sudo apt update && sudo apt upgrade -y
+  chezmoi update
+  ```
+  On Linux, `chezmoi` focuses on configuration. Package updates work best through the OS package manager to avoid `sudo` conflicts.
+- **Font issues**: If icons are missing, run `./install/provision/run_onchange_50-install-fonts.sh.tmpl` manually via `chezmoi apply` or source directly with `bash`.
+
+### Windows (WSL2)
+
+**Primary manager**: `apt-get` (inside WSL)
+
+- **Update**: Same as Linux.
+- **Clipboard**: Dotfiles configures `win32yank.exe` automatically for clipboard sharing.
+- **Performance**: Keep project files inside the Linux filesystem (`~/projects`), not in `/mnt/c/`, for dramatically better IO.
+
+---
+
+## Workflows
+
+### Apply changes
+
+After editing any config file:
+
+```bash
+dot apply
+```
+
+Triggers `dot_zshrc` reload and audit logging.
+
+### Upgrade-safe apply (recommended)
+
+```bash
+git pull
+DOTFILES_NONINTERACTIVE=1 dot apply --force
+dot doctor
+```
+
+`dot apply` includes post-apply checks that:
+- Remove stale read-only zsh cache files (`~/.config/shell/*.zwc`, `~/.config/zsh/**/*.zwc`)
+- Validate that `dot` resolves to `~/.local/bin/dot` in a fresh login shell
+
+Finish by reloading your session (`exec zsh`) or restarting the terminal.
+
+### Async updates
+
+Run updates in the background; you'll get a status banner on the next shell launch:
+
+```bash
+dot update --async
+```
+
+### Roll back
+
+If an update breaks your setup:
+
+```bash
+cd ~/.dotfiles
+git reset --hard HEAD@{1}
+chezmoi apply
+```
+
+### Offline / air-gapped mode
+
+```bash
+# 1. On a connected machine, bundle your setup:
+dot bundle ~/Downloads
+
+# 2. Transfer the archive to the offline machine, then:
+tar --zstd -xf dotfiles_offline_bundle_*.tar.zst -P
+cd ~/.dotfiles
+./install.sh --force
+```
+
+### Pre-warm caches
+
+Regenerate all tool caches to eliminate shell startup latency:
+
+```bash
+dot prewarm
+```
+
+### Debug
+
+If something's slow or broken:
+
+1. **Check health**:
+   ```bash
+   dot doctor
+   dot health --fix
+   ```
+2. **Smoke test**:
+   ```bash
+   dot smoke-test
+   ```
+3. **Scorecard**:
+   ```bash
+   dot scorecard
+   ```
+4. **Chaos testing (self-healing)**:
+   ```bash
+   dot chaos --force
+   dot heal --force
+   ```
+5. **Startup profiling**:
+   ```bash
+   dot perf --profile
+   ```
+6. **Post-merge verification**:
+   ```bash
+   dot verify
+   ```
+7. **Inspect alias behavior**:
+   ```bash
+   dot aliases list
+   dot aliases why dprune
+   DOTFILES_ALIAS_POLICY=strict bash ~/.dotfiles/scripts/diagnostics/alias-governance.sh
+   ```
+8. **Verbose mode**:
+   ```bash
+   DOTFILES_DEBUG=1 dot apply
+   ```
+
+### Safety flags
+
+Destructive aliases are disabled by default. Enable only when needed:
+
+```bash
+export DOTFILES_ENABLE_DANGEROUS_ALIASES=1
+```
+
+### Tiered alias loading
+
+Core aliases load eagerly. Ecosystem aliases are lazy-loaded and can be filtered:
+
+```bash
+export DOTFILES_ALIAS_ECOSYSTEMS=python,node
+```
+
+Valid ecosystem tags: `python`, `node`, `rust`, `network`, `legacy`.

package/docs/operations/RELIABILITY.md

@@ -0,0 +1,116 @@
+# Reliability
+
+## Reliability scorecard
+
+- Unit coverage: 100% module mapping target, enforced by `tests/framework/module_coverage.sh`
+- Integration depth: 11 integration test files in `tests/integration/`
+- Regression automation: 436 discovered test files and 2149 named tests in the current baseline
+
+## Coverage gap map
+
+| Module | Missing path | Risk level | Proposed test case |
+| :--- | :--- | :--- | :--- |
+| `scripts/qa/reliability-audit.sh` | Quick mode and integration mode branch handling | Closed | Covered by `tests/unit/misc/test_qa_reliability_behaviour.sh` |
+| `scripts/git-hooks/pre-push` | Audit command failure path | Closed | Covered by `tests/unit/misc/test_git_hooks_pre_push_behaviour.sh` |
+| `tests/framework/module_coverage.sh` | False-positive module matches | Closed | Covered by `tests/unit/misc/test_module_coverage_behaviour.sh` |
+| `examples/*.sh` | Drift between examples and real commands | Closed | Examples execute in CI through `Examples Contract` and `validate-examples.sh` |
+
+## Integration boundaries
+
+```mermaid
+flowchart LR
+  Dev[Developer] --> Hook[pre-push hook]
+  Hook --> Audit[reliability-audit.sh]
+  Audit --> Syntax[Shell syntax gate]
+  Audit --> Unit[Unit suite]
+  Audit --> Coverage[Module coverage]
+  Audit --> Examples[Example validation]
+  Audit --> WSL[WSL contract]
+  Audit --> Integration[Integration suite]
+  Integration --> Repo[Dotfiles workflows]
+  WSL --> Repo
+```
+
+```mermaid
+sequenceDiagram
+  participant Dev as Developer
+  participant Git as Git client
+  participant Hook as pre-push
+  participant Audit as reliability-audit.sh
+  participant Suite as tests/framework/test_runner.sh
+  participant Cov as module_coverage.sh
+  participant Ex as validate-examples.sh
+  participant WSL as wsl-contract.sh
+
+  Dev->>Git: git push
+  Git->>Hook: invoke pre-push
+  Hook->>Hook: verify signed commits
+  Hook->>Audit: run quick gate
+  Audit->>Suite: run unit suite
+  Audit->>Cov: enforce 100% module mapping
+  Audit->>Ex: execute examples
+  Audit->>WSL: verify WSL parity contract
+  Ex-->>Audit: pass
+  Cov-->>Audit: pass
+  WSL-->>Audit: pass
+  Suite-->>Audit: pass
+  Audit-->>Hook: pass
+  Hook-->>Git: allow push
+```
+
+## CI gate
+
+```yaml
+name: Reliability Gate
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+jobs:
+  reliability:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Reliability audit
+        run: bash ./scripts/qa/reliability-audit.sh --with-integration
+
+  examples-contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Validate executable examples
+        run: bash ./scripts/qa/validate-examples.sh
+
+  wsl-contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Validate WSL parity contract
+        run: bash ./scripts/qa/wsl-contract.sh
+
+  reliability-summary:
+    needs: [reliability, examples-contract, wsl-contract]
+    runs-on: ubuntu-latest
+```
+
+## Functional examples
+
+- `examples/example-test-suite.sh`: Runs a focused unit slice.
+- `examples/example-coverage-gate.sh`: Runs the module coverage contract.
+- `examples/example-git-hooks.sh`: Shows the local hook entrypoints.
+- `examples/example-platform-contract.sh`: Shows the platform and host contract across macOS, Linux, and WSL.
+
+## Local guardrail
+
+`make test` is the canonical reliability command. It runs syntax checks, unit tests, module coverage, executable examples, and integration tests.
+
+For a lightweight repository-wide snapshot, run `bash ./scripts/qa/coverage-baseline.sh --with-module-coverage`.
+
+Core internal behaviors are traced through `bash ./scripts/qa/traceability-coverage.sh`.

package/docs/{ROADMAP.md → operations/ROADMAP.md}

@@ -20,9 +20,9 @@ This roadmap steers the project from a "feature-rich dotfiles repo" to an **Ente
 **Goal:** "Observable Shell Lifecycle".
 > *The shell is instrumented: failures, timing, and lifecycle events are visible by design.*
 
-- [ ] **Audit Structuring**: JSON-structured logging for bootstrap and provisioning events.
-- [ ] **Debug Modes**: First-class support for `DOTFILES_DEBUG=1` and `DOTFILES_TRACE=1`.
-- [ ] **Telemetry (Local)**: Granular startup timing breakdown (init vs plugins vs prompt).
+- [x] **Audit Structuring**: JSON-structured logging for bootstrap and provisioning events.
+- [x] **Debug Modes**: First-class support for `DOTFILES_DEBUG=1` and `DOTFILES_TRACE=1`.
+- [x] **Telemetry (Local)**: Granular startup timing breakdown via `dot perf`.
 - [ ] **Health Dashboard (Phase 39)**: CLI view of system "health" metrics.
 - [ ] **System Status (Phase 39)**: Real-time resource usage, battery, and network stats.
 - [ ] **Update Manager (Phase 39)**: Visual interface for tool updates and migration.
@@ -31,8 +31,8 @@ This roadmap steers the project from a "feature-rich dotfiles repo" to an **Ente
 **Goal:** "Explicit Secrets Model".
 > *Secrets are never committed; sensitive state is encrypted or host-local by default.*
 
-- [ ] **Secret Driver**: Native integration with 1Password/Bitwarden CLI via `chezmoi`.
-- [ ] **Encryption**: Promoted use of `age` encryption for all private config files.
+- [x] **Secret Driver**: Native integration with 1Password/Bitwarden CLI via `chezmoi`.
+- [x] **Encryption**: Promoted use of `age` encryption for all private config files.
 - [ ] **Leak Prevention (Phase 29)**: Pre-commit hooks (TruffleHog/Gitleaks) for high-entropy detection.
 - [ ] **Vault Integration (Phase 29)**: Native HashiCorp Vault support.
 - [ ] **Hardware Enclaves (Phase 29)**: Support for Secure Enclave/TPM key storage.
@@ -65,7 +65,7 @@ This roadmap steers the project from a "feature-rich dotfiles repo" to an **Ente
 **Goal:** "Documented Threat Model".
 > *Security decisions are driven by an explicit, documented threat model.*
 
-- [ ] **Threat Model Doc**: A lightweight document defining the trust boundary (Local Machine).
+- [x] **Threat Model Doc**: A lightweight document defining the trust boundary (Local Machine). See `docs/security/THREAT_MODEL.md`.
 - [ ] **Supply Chain**: Verification steps for upstream dependencies.
 - [ ] **Identity & Access (Phase 40)**:
     - [ ] **SSH Certs**: Short-lived SSH Certificates.
@@ -77,9 +77,9 @@ This roadmap steers the project from a "feature-rich dotfiles repo" to an **Ente
 **Goal:** "Self-Validating Environment".
 > *The environment can validate itself after installation or update.*
 
-- [ ] **Smoke Tests**: Automated verification of key aliases (`ls`, `git`, `docker`).
-- [ ] **CI Validation**: GitHub Actions workflow to boot and verify the shell syntax.
-- [ ] **Chaos Engineering (Phase 41)**:
+- [x] **Smoke Tests**: Automated verification of key aliases (`ls`, `git`, `docker`).
+- [x] **CI Validation**: GitHub Actions workflow to boot and verify the shell syntax.
+- [x] **Chaos Engineering (Phase 41)**:
     - [ ] **Config Chaos**: Randomly corrupt config files to test recovery.
     - [ ] **Network Simulation**: Simulate high latency/packet loss.
     - [ ] **Permission Fuzzing**: Verify strict umask behavior.
@@ -88,13 +88,13 @@ This roadmap steers the project from a "feature-rich dotfiles repo" to an **Ente
 **Goal:** "Supported Platforms Matrix".
 > *Only listed platforms are guaranteed to work; others are best-effort.*
 
-- [ ] **Support Matrix**: Explicit table of OS/Version support (macOS 14+, Ubuntu 24.04+, WSL2).
+- [x] **Support Matrix**: Explicit table of OS/Version support. See `docs/reference/SUPPORT_MATRIX.md`.
 - [ ] **Windows Deep Integration (Phase 53)**:
     - [ ] **PowerShell Profile**: Mirror Zsh functionality.
     - [ ] **WinGet**: Declarative package management.
     - [ ] **WSL Bridge**: Seamless interop.
 - [ ] **Linux Deep Integration (Phase 55)**:
-    - [ ] **Systemd User Units**: User service management.
+    - [x] **Systemd User Units**: User service management.
     - [ ] **Desktop Envs**: GNOME/KDE/Sway configs.
 
 ---

package/docs/operations/TESTING.md

@@ -0,0 +1,195 @@
+# Testing strategy
+
+## Overview
+
+The repo uses a multi-layer testing approach: unit tests for individual functions, integration tests for system-wide behavior, and performance benchmarks for resource efficiency.
+
+## Quick start
+
+```bash
+# Run all unit tests
+./tests/framework/test_runner.sh
+
+# Run a specific test suite
+./tests/framework/test_runner.sh extract
+
+# Run integration tests
+RUN_INTEGRATION=1 ./tests/framework/test_runner.sh
+
+# Run performance benchmarks
+./tests/performance/benchmark_runner.sh
+```
+
+## Test structure
+
+```text
+tests/
+├── framework/           # Test framework
+│   ├── assertions.sh    # 16 assertion functions
+│   ├── mocks.sh        # Mock utilities
+│   └── test_runner.sh  # Test executor
+├── unit/               # 425 unit test files
+├── integration/        # 11 integration test files
+└── performance/        # Benchmarks
+```
+
+## Writing tests
+
+### Test file template
+
+```bash
+#!/usr/bin/env bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../framework/assertions.sh"
+
+# Source the function under test
+source "$HOME/.dotfiles/.chezmoitemplates/functions/myfunction.sh"
+
+# Test cases
+test_start "function_basic_usage"
+assert_exit_code 0 "myfunction arg1"
+
+test_start "function_no_args"
+assert_exit_code 1 "myfunction"
+```
+
+### Available assertions
+
+| Function | Description |
+|----------|-------------|
+| `assert_equals expected actual [msg]` | Two values are equal |
+| `assert_not_equals unexpected actual [msg]` | Two values differ |
+| `assert_exit_code code command` | Command exits with given code |
+| `assert_output_contains needle command` | Output contains string |
+| `assert_output_not_contains needle command` | Output lacks string |
+| `assert_output_matches pattern command` | Output matches regex |
+| `assert_file_exists path [msg]` | File exists |
+| `assert_file_not_exists path [msg]` | File doesn't exist |
+| `assert_dir_exists path [msg]` | Directory exists |
+| `assert_dir_not_exists path [msg]` | Directory doesn't exist |
+| `assert_true condition [msg]` | Condition is true |
+| `assert_false condition [msg]` | Condition is false |
+| `assert_empty value [msg]` | String is empty |
+| `assert_not_empty value [msg]` | String isn't empty |
+| `assert_file_contains file needle [msg]` | File contains text |
+| `assert_file_not_contains file needle [msg]` | File lacks text |
+
+### Mock utilities
+
+| Function | Description |
+|----------|-------------|
+| `mock_init` | Initialize mock environment |
+| `mock_command name output [exit_code]` | Create a mock command |
+| `mock_command_spy name [output] [exit_code]` | Create a mock that records calls |
+| `mock_get_calls name` | Get spy call history |
+| `mock_call_count name` | Get number of spy calls |
+| `mock_file content [filename]` | Create temp file with content |
+| `mock_dir [prefix]` | Create temp directory |
+| `mock_archive type [content]` | Create a mock archive file |
+| `mock_env var_name value` | Set an environment variable |
+| `mock_cleanup` | Clean up all mocks |
+
+## Test categories
+
+### Unit tests (`tests/unit/`)
+
+Test individual functions in isolation. Each file follows the `test_*.sh` naming convention and is discoverable with `ls tests/unit/`.
+
+### Integration tests (`tests/integration/`)
+
+Test complete workflows like the installation script and end-to-end apply behavior.
+
+### Performance tests (`tests/performance/`)
+
+Measure resource efficiency with shell startup benchmarks and load tests.
+
+## Coverage goals
+
+| Category | Target | Current |
+|----------|--------|---------|
+| Module coverage | >=95% | 100% |
+| Unit test files | - | 425 |
+| Integration test files | - | 11 |
+| Total test files | - | 436 |
+| Named tests (`test_start`) | - | 2149 |
+| Unit test pass rate | 100% | 100% |
+
+CI enforces module coverage via:
+
+```bash
+MIN_COVERAGE=95 ./tests/framework/module_coverage.sh
+```
+
+For a current local baseline, run:
+
+```bash
+bash ./scripts/qa/coverage-baseline.sh --with-module-coverage
+```
+
+For core internal behavior traceability, run:
+
+```bash
+bash ./scripts/qa/traceability-coverage.sh
+```
+
+## CI integration
+
+Tests run automatically on every push to main, every pull request, and weekly scheduled runs (Monday 6 AM UTC).
+
+### GitHub Actions example
+
+```yaml
+- name: Run Tests
+  run: |
+    chmod +x ./tests/framework/test_runner.sh
+    ./tests/framework/test_runner.sh
+
+- name: Run Integration Tests
+  run: |
+    RUN_INTEGRATION=1 ./tests/framework/test_runner.sh
+
+- name: Run Performance Benchmarks
+  run: |
+    ./tests/performance/benchmark_runner.sh
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RUN_INTEGRATION` | `0` | Set to `1` to include integration tests |
+| `VERBOSE` | `0` | Set to `1` for verbose output |
+| `REPO_ROOT` | Auto-detected | Repository root directory |
+| `TESTS_DIR` | Auto-detected | Tests directory |
+
+## Best practices
+
+1. **Isolation** -- Each test should be independent and self-contained.
+2. **Cleanup** -- Use mocks that auto-cleanup via traps.
+3. **No sleep** -- Avoid `sleep` or hardcoded delays.
+4. **Descriptive names** -- Test names should describe what's being verified.
+5. **Edge cases** -- Test error conditions, not just happy paths.
+6. **Security** -- Include tests for dangerous input rejection.
+
+## Troubleshooting
+
+### Tests not found
+
+Make sure test files match the `test_*.sh` pattern and are executable:
+
+```bash
+chmod +x tests/unit/test_*.sh
+chmod +x tests/integration/test_*.sh
+```
+
+### Function not available
+
+If a test reports "function not available", verify the source file exists:
+
+```bash
+ls -la .chezmoitemplates/functions/
+```
+
+### Mock cleanup issues
+
+If mocks aren't cleaning up, make sure you aren't running with `set -e` before mock operations that might intentionally fail.

package/docs/operations/TRACEABILITY.md

@@ -0,0 +1,31 @@
+# Behavioral Traceability
+
+This matrix ties core internal behaviors to implementation files, automated tests, and prose documentation.
+
+It is enforced by `bash ./scripts/qa/traceability-coverage.sh`.
+
+| Behavior ID | Behavior | Implementation | Test Evidence | Documentation |
+|-------------|----------|----------------|---------------|---------------|
+| BT-01 | AI status, launcher, and cache lifecycle | `scripts/dot/commands/ai.sh` | `tests/unit/dot-cli/test_dot_commands_ai.sh` | `docs/AI.md`, `docs/reference/UTILS.md` |
+| BT-02 | Agent profiles, checkpoints, and conformance | `scripts/dot/commands/agent.sh` | `tests/unit/dot-cli/test_dot_commands_agent.sh`, `tests/unit/dot-cli/test_dot_agent_mode.sh`, `tests/unit/dot-cli/test_dot_a2a_conformance.sh` | `docs/operations/TRUSTED_AGENT_WORKSTATION.md`, `docs/interop/A2A.md`, `docs/reference/UTILS.md` |
+| BT-03 | MCP policy validation and registry inspection | `scripts/dot/commands/meta.sh`, `scripts/diagnostics/mcp-doctor.sh` | `tests/unit/dot-cli/test_dot_commands_meta.sh`, `tests/unit/dot-cli/test_dot_cli.sh` | `docs/security/MCP_POLICY.md`, `docs/operations/TRUSTED_AGENT_WORKSTATION.md`, `docs/reference/UTILS.md` |
+| BT-04 | Fleet status, drift, namespace, and events workflows | `scripts/dot/commands/fleet.sh` | `tests/unit/dot-cli/test_dot_commands_fleet.sh`, `tests/unit/dot-cli/test_dot_fleet_enforcement.sh` | `docs/operations/TRUSTED_AGENT_WORKSTATION.md`, `docs/operations/ATTESTATION.md`, `docs/reference/UTILS.md` |
+| BT-05 | Secrets command surface and shell autoload buckets | `scripts/dot/commands/secrets.sh`, `dot_config/shell/10-secrets.sh` | `tests/unit/dot-cli/test_dot_commands_secrets.sh`, `tests/unit/shell/test_shell_secrets_autoload.sh` | `docs/security/SECRETS.md`, `docs/reference/UTILS.md` |
+| BT-06 | Theme synchronization and multi-tool theme application | `dot_local/bin/executable_dot-theme-sync` | `tests/unit/theme/test_dot_theme_sync.sh` | `docs/guides/THEMING.md`, `docs/reference/THEMES.md`, `docs/reference/SCRIPTS.md` |
+| BT-07 | Reliability audit orchestration | `scripts/qa/reliability-audit.sh` | `tests/unit/misc/test_qa_reliability.sh`, `tests/unit/misc/test_qa_reliability_behaviour.sh` | `docs/operations/RELIABILITY.md`, `docs/operations/TESTING.md` |
+| BT-08 | Repository coverage baseline audit | `scripts/qa/coverage-baseline.sh` | `tests/unit/misc/test_qa_coverage_baseline.sh` | `docs/operations/RELIABILITY.md`, `docs/operations/TESTING.md` |
+| BT-09 | Documentation coverage contract for public surfaces | `scripts/qa/docs-coverage.sh` | `tests/unit/misc/test_qa_docs_coverage.sh`, `tests/unit/misc/test_qa_docs_repo_coverage.sh` | `docs/operations/RELIABILITY.md`, `docs/reference/UTILS.md`, `docs/reference/SCRIPTS.md` |
+| BT-10 | Repository executable-surface coverage gate | `tests/framework/module_coverage.sh` | `tests/unit/tools/test_public_entrypoints.sh`, `tests/unit/misc/test_module_coverage_behaviour.sh` | `docs/operations/TESTING.md`, `docs/security/VERIFICATION_VALIDATION.md`, `docs/reference/SCRIPTS.md` |
+| BT-11 | Core apply, diff, status, edit, and commit workflows | `scripts/dot/commands/core.sh` | `tests/unit/dot-cli/test_dot_commands_core.sh`, `tests/unit/dot-cli/test_dot_cli.sh` | `docs/reference/UTILS.md` |
+| BT-12 | Alias discovery, search, and governance workflows | `scripts/dot/commands/aliases.sh` | `tests/unit/dot-cli/test_dot_commands_aliases.sh` | `docs/reference/ALIASES.md`, `docs/reference/UTILS.md` |
+| BT-13 | Appearance and theme command workflows | `scripts/dot/commands/appearance.sh` | `tests/unit/dot-cli/test_dot_commands_appearance.sh` | `docs/guides/THEMING.md`, `docs/reference/UTILS.md` |
+| BT-14 | Diagnostics command workflows | `scripts/dot/commands/diagnostics.sh` | `tests/unit/dot-cli/test_dot_commands_diagnostics.sh` | `docs/operations/RELIABILITY.md`, `docs/reference/UTILS.md` |
+| BT-15 | Lint command workflow | `scripts/dot/commands/lint.sh` | `tests/unit/dot-cli/test_dot_commands_lint.sh`, `tests/unit/dot-cli/test_lint.sh` | `docs/operations/TESTING.md`, `docs/reference/UTILS.md` |
+| BT-16 | AI steering pattern workflows | `scripts/dot/commands/patterns.sh` | `tests/unit/dot-cli/test_dot_commands_patterns.sh` | `docs/AI.md` |
+| BT-17 | Restore and rollback workflows | `scripts/dot/commands/restore.sh` | `tests/unit/dot-cli/test_dot_commands_restore.sh` | `docs/reference/UTILS.md` |
+| BT-18 | Security command workflows | `scripts/dot/commands/security.sh` | `tests/unit/dot-cli/test_dot_commands_security.sh` | `docs/reference/UTILS.md`, `docs/security/COMPLIANCE.md` |
+| BT-19 | Tool catalog and sandbox workflows | `scripts/dot/commands/tools.sh` | `tests/unit/dot-cli/test_dot_commands_tools.sh` | `docs/reference/TOOLS.md`, `docs/reference/UTILS.md` |
+| BT-20 | Example validation contract | `scripts/qa/validate-examples.sh` | `tests/unit/misc/test_qa_reliability.sh` | `docs/operations/RELIABILITY.md` |
+| BT-21 | WSL parity contract | `scripts/qa/wsl-contract.sh` | `tests/unit/misc/test_qa_reliability.sh` | `docs/operations/RELIABILITY.md`, `docs/reference/SUPPORT_MATRIX.md` |
+| BT-22 | Internal behavior traceability contract | `scripts/qa/traceability-coverage.sh` | `tests/unit/misc/test_qa_traceability_coverage.sh` | `docs/operations/TRACEABILITY.md`, `docs/operations/RELIABILITY.md` |
+| BT-23 | Multi-format Manual pipeline | `scripts/docs/build-manual.sh`, `scripts/docs/check-manual.sh`, `scripts/dot/commands/manual.sh` | `tests/unit/docs/test_build_manual.sh`, `tests/unit/docs/test_check_manual.sh`, `tests/unit/dot-cli/test_dot_commands_manual.sh` | `docs/manual/`, `docs/README.md`, `README.md` |

package/docs/operations/TRUSTED_AGENT_WORKSTATION.md

@@ -0,0 +1,61 @@
+# Trusted Agent Workstation
+
+This repository is more than shell setup.
+
+It defines a signed, local-first workstation baseline for agentic development on macOS, Linux, WSL, and PowerShell.
+
+## Core model
+
+- bounded agent profiles
+- tracked MCP policy and registry
+- workstation attestation
+- signed commits and verified merges
+- cross-platform CLI and diagnostics
+
+## Governance artifacts
+
+The source of truth lives in tracked JSON artifacts:
+
+- [policy-bundles.json](/home/seb/.dotfiles/dot_config/dotfiles/policy-bundles.json)
+- [agent-profiles.json](/home/seb/.dotfiles/dot_config/dotfiles/agent-profiles.json)
+- [mcp-policy.json](/home/seb/.dotfiles/dot_config/dotfiles/mcp-policy.json)
+- [mcp-registry.json](/home/seb/.dotfiles/dot_config/dotfiles/mcp-registry.json)
+- [model-registry.json](/home/seb/.dotfiles/dot_config/dotfiles/model-registry.json)
+- [prompt-registry.json](/home/seb/.dotfiles/dot_config/dotfiles/prompt-registry.json)
+
+## Enterprise path
+
+Phase 1 establishes:
+
+- product framing
+- policy bundles
+- prompt and model change control
+- attestation evidence for governance state
+
+Implemented next-layer controls:
+
+- filesystem-backed fleet attestation export
+- replayable agent checkpoints
+- signed policy bundle release workflow
+- tracked A2A conformance validation
+
+Further phases add:
+
+- central audit export
+- fleet drift dashboards
+- checkpoint policies and retention controls
+- broader protocol interoperability coverage
+
+## Validation
+
+Run:
+
+```bash
+dot doctor
+dot mcp --strict
+dot mode list
+dot agent card --json
+dot attest --json
+```
+
+Every governance change requires a signed commit.