docs(cli): clarifier usage CI/CD et workspace apply

Author: raidos23

docs/ci_cd_ark_cli.md

@@ -6,10 +6,9 @@ This page provides a practical and reproducible CI/CD flow using `pycompiler_ark
 
 Automate the following steps for a workspace:
 
-1. Initialize workspace base files
-2. Detect/configure the entrypoint
-3. Run a strict precheck gate
-4. Compile with a selected engine
+1. Apply workspace setup in one deterministic step
+2. Run a strict precheck gate
+3. Compile with a selected engine
 
 ## Prerequisites
 
@@ -30,17 +29,20 @@ ARK_BIN="python3 /path/to/PyCompiler_ARK/pycompiler_ark.py"
 WORKSPACE_DIR="/path/to/workspace"
 ENGINE_ID="pyinstaller"
 
-$ARK_BIN init "$WORKSPACE_DIR" --with-venv --json > "$WORKSPACE_DIR/.ark_init.json"
-$ARK_BIN cfg-auto "$WORKSPACE_DIR" --json > "$WORKSPACE_DIR/.ark_cfg_auto.json"
+# Single-step workspace flow (init + auto-config + inspect)
+$ARK_BIN workspace apply "$WORKSPACE_DIR" --with-venv --strict --json > "$WORKSPACE_DIR/.ark_workspace_apply.json"
+
+# Optional explicit gate (kept in many teams for readability in CI logs)
 $ARK_BIN check "$WORKSPACE_DIR" --json --strict > "$WORKSPACE_DIR/.ark_check.json"
 
 ENTRYPOINT_REL="$(python3 - <<'PY'
 import json, os
 from pathlib import Path
 ws = os.environ["WORKSPACE_DIR"]
-cfg = Path(ws) / ".ark_cfg_auto.json"
-data = json.loads(cfg.read_text(encoding="utf-8"))
-print(data.get("entrypoint") or "main.py")
+report = Path(ws) / ".ark_workspace_apply.json"
+data = json.loads(report.read_text(encoding="utf-8"))
+inspect_payload = data.get("inspect") or {}
+print(inspect_payload.get("entrypoint") or "main.py")
 PY
 )"
 ENTRYPOINT_FILE="$WORKSPACE_DIR/$ENTRYPOINT_REL"
@@ -51,14 +53,11 @@ $ARK_BIN engine compile "$ENGINE_ID" "$ENTRYPOINT_FILE" --workspace "$WORKSPACE_
 
 ## Command Breakdown
 
-- `init --with-venv`
-  - prepares workspace
-  - creates `ARK_Main_Config.yml`, `bcasl.yml`, `.ark/pref.json`
-  - creates/reuses a local virtual environment
-
-- `cfg-auto`
-  - detects an entrypoint
-  - updates workspace configuration
+- `workspace apply --with-venv --strict`
+  - applies full workspace setup in one command
+  - creates/reuses `ARK_Main_Config.yml`, `bcasl.yml`, `.ark/pref.json`
+  - runs auto-config (unless disabled)
+  - can fail with strict precheck semantics when entrypoint is required
 
 - `check --strict`
   - CI/CD gate
@@ -67,6 +66,43 @@ $ARK_BIN engine compile "$ENGINE_ID" "$ENTRYPOINT_FILE" --workspace "$WORKSPACE_
 - `engine compile`
   - compiles the resolved entrypoint with the selected engine
 
+## Workspace Apply Options (CI-focused)
+
+`workspace apply` (and alias `workspace select`) supports options designed for pipelines:
+
+- `--with-venv`
+  - create/reuse workspace virtual environment
+- `--entrypoint <path>`
+  - force entrypoint instead of relying on detection
+- `--no-auto-config`
+  - skip auto-configuration stage (useful for fully pre-committed config flows)
+- `--no-inspect-files`
+  - skip recursive `.py` workspace scan
+- `--no-apply-venv-pref`
+  - skip applying `.ark/pref.json` workspace venv preference
+- `--no-apply-engine-configs`
+  - skip loading `.ark/<engine_id>/config.json` workspace engine configs
+- `--strict`
+  - fail when required checks are missing
+- `--require-entrypoint`
+  - explicit entrypoint requirement (also implied by `--strict`)
+- `--json`
+  - machine-readable output for pipeline parsing
+
+Examples:
+
+```bash
+# Strict default for CI
+python3 /path/to/PyCompiler_ARK/pycompiler_ark.py workspace apply /path/to/workspace --with-venv --strict --json
+
+# Explicit entrypoint override
+python3 /path/to/PyCompiler_ARK/pycompiler_ark.py workspace apply /path/to/workspace --entrypoint src/main.py --json
+
+# Alias forms
+python3 /path/to/PyCompiler_ARK/pycompiler_ark.py workspace select /path/to/workspace --json
+python3 /path/to/PyCompiler_ARK/pycompiler_ark.py ws apply /path/to/workspace --json
+```
+
 ## Choosing an Engine
 
 List available engines:
@@ -89,23 +125,23 @@ Common choices:
 - `4`: invalid workspace
 - `5`: engine not found
 
-## Ready-to-use Script
+## Reusable Shell Wrapper (optional)
 
-A concrete validated example can be run with:
+If your team prefers a checked-in shell wrapper, create a script that chains:
 
-```bash
-./ci_cd_ark.sh
-```
+1. `workspace apply ... --json`
+2. `check ... --json --strict`
+3. `engine compile ... --json`
 
-This script chains `init`, `cfg-auto`, `check`, and `engine compile`, and writes JSON reports.
+Then archive JSON outputs as CI artifacts for troubleshooting.
 
 ## GitHub Actions Dogfooding Workflow
 
 This repository includes a workflow where ARK compiles itself using ARK CLI:
 
 - Workflow file: `.github/workflows/ark-self-build.yml`
 - Engine used: `nuitka`
-- Flow: `init` -> `cfg-auto` -> `check --strict` -> `engine compile`
+- Flow: `workspace apply` (or `init` + `cfg-auto`) -> `check --strict` -> `engine compile`
 - Uploaded artifacts:
   - build output (`dist/`, `build/` when available)
   - ARK workspace reports (`.ark_ci_artifacts/*.json`)
@@ -121,6 +157,16 @@ This repository includes a workflow where ARK compiles itself using ARK CLI:
 - Keep `.ark_*.json` files as CI artifacts for debugging.
 - Start with `pyinstaller`, then evaluate `nuitka` if you want runtime performance optimization.
 
+## GUI Selection Equivalent in CLI
+
+When users say "select workspace" in GUI terms, the CI/CD equivalent is:
+
+```bash
+python3 /path/to/PyCompiler_ARK/pycompiler_ark.py workspace apply /path/to/workspace --with-venv --strict
+```
+
+This gives a deterministic, scriptable workflow that mirrors the practical setup steps usually performed after selecting a workspace in the GUI.
+
 ## Reproducibility Note for Engine Options
 
 For full reproducibility, engine-specific options should be configured from the GUI first.