feat: add workspace configuration with --workspace flag and env var

.gitignore

@@ -32,7 +32,8 @@ dist
 # testing complytime created by openscap-plugin
 user_workspace
 complyctl.log
-.complytime
+.complytime/**
+!.complytime/complytime.yaml
 
 # Outputs
 assessment-plan.json

AGENTS.md

@@ -276,6 +276,7 @@ packages organized by domain responsibility.
 <!-- MANUAL ADDITIONS END -->
 
 ## Recent Changes
+- workspace-configuration: `--workspace` flag and `COMPLYTIME_WORKSPACE` env var for workspace directory resolution; config file moved to `.complytime/complytime.yaml` with legacy fallback; `NewWorkspace(baseDir string)` signature change; all output paths relative to resolved workspace
 - scan-error-exit-codes: `complyctl scan` exits non-zero on operational errors; `ScanResponse.errors` proto field added; `ScanResult`/`RouteScanResult()` in `pkg/provider/manager.go`; `FormatOperationalWarnings` in `internal/output/scan_summary.go`; `processScanOutput`/`checkOperationalErrors`/`reportOperationalWarnings` in `cmd/complyctl/cli/scan.go`
 - 005-bundle-resolver-alignment: Policy resolver supports both split-layer and Gemara bundle-format OCI artifacts; `internal/policy/loader.go` gained `LoadBundleFiles()`, `DetectManifestShape()`, `resolveManifest()`; `PolicyLoader` interface extended with bundle methods; `MockBundlePolicySource` added to `internal/cache/cachetest/`
 - 005-rpm-packaging-ci: Added Go 1.25 + go-rpm-macros, Packit, Testing Farm (TMT/FMF)

CHANGELOG.md

@@ -4,10 +4,19 @@
 
 ### Added
 
+- Workspace configuration: `--workspace` / `-w` flag and `COMPLYTIME_WORKSPACE` environment variable for running commands from any directory (#433)
+- Config file location: `complytime.yaml` moved to `.complytime/complytime.yaml` with backward compatibility (#527)
+- Deprecation warning for legacy config file location at repository root
 - Cross-repo integration test infrastructure validating the complyctl + Ampel
   provider pipeline end-to-end (`tests/cross-repo/`, `make test-cross-repo`).
 - CI workflow `ci_cross_repo_integration.yml` that builds complyctl from the PR
   branch and complytime-providers from main, then runs the full get → generate →
   scan pipeline with real snappy and ampel binaries.
 - Minimal test Gemara policy (`policies/test-branch-protection`) seeded in the
   mock OCI registry for integration testing.
+
+### Changed
+
+- All commands now accept `--workspace` flag to specify workspace directory
+- `NewWorkspace()` function signature changed from `NewWorkspace()` to `NewWorkspace(baseDir string)`
+- Log file and scan output paths are now relative to resolved workspace directory

README.md

@@ -38,12 +38,11 @@ A lightweight compliance runtime that pulls [Gemara](https://gemara.openssf.org/
 │                                           │ Generate, Scan │     │
 │  ┌──────────────┐                         └────────────────┘     │
 │  │  Workspace   │                                                │
-│  │              │  complytime.yaml defines:                      │
-│  │ ./complytime │   - registry URL                               │
-│  │   .yaml      │   - policy IDs + versions                      │
-│  │              │   - targets + variables                        │
-│  │ ./.comply-   │                                                │
-│  │   time/scan/ │                                                │
+│  │              │  .complytime/complytime.yaml defines:           │
+│  │ .complytime/ │   - registry URL                               │
+│  │  complytime  │   - policy IDs + versions                      │
+│  │   .yaml      │   - targets + variables                        │
+│  │  scan/       │                                                │
 │  │  (output)    │  Scan output (EvaluationLog, OSCAL,            │
 │  └──────────────┘   SARIF, Markdown) written to workspace        │
 └──────────────────────────────────────────────────────────────────┘
@@ -54,7 +53,7 @@ A lightweight compliance runtime that pulls [Gemara](https://gemara.openssf.org/
 | Component | Description |
 |:---|:---|
 | **OCI Registry** | Remote store for Gemara policies. Supports two OCI manifest layouts: split-layer (distinct media types per artifact) and Gemara bundle format (single artifact media type with annotation-based differentiation). Both formats are auto-detected and resolved transparently. |
-| **Workspace** | Current directory containing `complytime.yaml`. Defines which registry, policies, and targets to use. Scan output lands in `./.complytime/scan/`. |
+| **Workspace** | Resolved workspace directory containing `.complytime/complytime.yaml` (or legacy `complytime.yaml` at root). Configurable via `--workspace` flag or `COMPLYTIME_WORKSPACE` env var. Defines which registry, policies, and targets to use. Scan output lands in `.complytime/scan/`. |
 | **Cache** | Local OCI Layout stores under `~/.complytime/policies/`. One store per policy ID. `state.json` tracks digests for incremental sync. |
 | **Providers** | Standalone executables in `~/.complytime/providers/` matching the `complyctl-provider-*` naming convention. Communicate via gRPC (`Describe`, `Generate`, `Scan`). Evaluator ID derived from filename. |
 | **CLI** | Orchestrates the workflow: fetch policies, resolve dependency graphs, dispatch to providers, produce compliance reports. |
@@ -79,15 +78,49 @@ A lightweight compliance runtime that pulls [Gemara](https://gemara.openssf.org/
 | `providers` | List discovered scanning providers and their health status |
 | `version` | Print version |
 
-Global flag: `--debug` / `-d` — output debug logs.
+Global flags: 
+- `--debug` / `-d` — output debug logs
+- `--workspace` / `-w` — workspace directory (project root containing `.complytime/`, defaults to current directory)
+
+### Run Commands from Any Directory
+
+Use the `--workspace` flag to run commands from any directory:
+
+```bash
+# Run from a different directory
+complyctl scan --workspace ~/projects/myapp
+
+# Using relative path
+complyctl scan --workspace ../myapp
+
+# Using environment variable
+export COMPLYTIME_WORKSPACE=~/projects/myapp
+complyctl scan
+```
+
+### Config File Location
+
+complyctl organizes all workspace-specific files under `.complytime/` to keep your repository root clean and avoid configuration conflicts.
+
+- `.complytime/complytime.yaml` - Configuration file (policies, targets, variables)
+- `.complytime/scan/` - Scan output reports
+- `.complytime/complyctl.log` - Debug log file
+- `.complytime/generation/` - Generation state (per-policy freshness tracking)
+
+**Note:** For backward compatibility, complyctl still supports `complytime.yaml` at the repository root, but this location is deprecated. Move your config to `.complytime/complytime.yaml`:
+
+```bash
+mkdir -p .complytime
+mv complytime.yaml .complytime/complytime.yaml
+```
 
 ### `init`
 
 ```bash
 complyctl init
 ```
 
-Creates a workspace configuration file (`complytime.yaml`). When one already exists, validates and runs `get` automatically.
+Creates a workspace configuration file (`.complytime/complytime.yaml`). Errors if one already exists.
 
 ### `get`
 
@@ -186,7 +219,7 @@ Lists discovered scanning providers with their evaluator ID, path, health status
 ## Workspace Configuration
 
 ```yaml
-# complytime.yaml
+# .complytime/complytime.yaml
 policies:
   - url: registry.example.com/policies/nist-800-53-r5@v1.0.0
     id: nist