opencomplai-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{opencomplai_cli-0.5.0 → opencomplai_cli-0.7.0}/.gitignore

@@ -86,3 +86,5 @@ tmp/
 
 # Scratch worktrees created by local agent tooling.
 .harness-worktrees/
+
+.vercel

{opencomplai_cli-0.5.0 → opencomplai_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opencomplai-cli
-Version: 0.5.0
+Version: 0.7.0
 Summary: Opencomplai command-line interface for EU AI Act compliance assessment
 Project-URL: Homepage, https://opencomplai.com
 Project-URL: Documentation, https://docs.opencomplai.com
@@ -50,13 +50,32 @@ meta-package instead.
 | `opencomplai init` | Scaffold a `system-manifest.json` for your project |
 | `opencomplai scan` | Corroborate the manifest against your code and report discrepancies |
 | `opencomplai check` | Run the compliance gate and write `compliance-artifact.json` |
-| `opencomplai dashboard` | Manage premium dashboard enrollment and sync |
+| `opencomplai push` | Publish a signed artifact (scan status or Annex IV dossier) to the Premium Dashboard |
+| `opencomplai checker` | Run the interactive EU AI Act applicability checker |
+| `opencomplai gaps` | Print a per-article EU AI Act gap report (informational — never gates CI) |
+| `opencomplai recommend` | Write copy-paste remediation templates for Missing/Partial gap-report rows |
+| `opencomplai report` | Render a single shareable HTML/PDF compliance report |
+| `opencomplai eval` | Run safety, bias, and data-leakage pipeline evaluators |
+| `opencomplai validate-manifest` | Validate a `system-manifest.json` against the required schema |
+| `opencomplai serve` | Start a localhost-only scan dashboard (not Pro/SaaS) |
+| `opencomplai approve` | Mint a signed HITL approval token for a `HALTED_PENDING_REVIEW` system |
+| `opencomplai resume` | Resume a `HALTED_PENDING_REVIEW` system with a signed approval token |
+| `opencomplai verify-output` | Verify an AI output claim against ground-truth sources |
+| `opencomplai version` | Show the installed Opencomplai version |
+| `opencomplai info` | Show full package metadata (`pip show`-style, across the whole suite) |
+
+Also available as command groups (`opencomplai <group> --help` for their own subcommands):
+`docs` (Annex IV dossier generation), `risk` (risk classification), `sync` (metadata sync),
+`keys` (signing-key rotation), `ai` (optional AI-intent plugin configuration), `controls`
+(control-register status).
 
 Run `opencomplai --help` for the full command list, or `opencomplai <command> --help` for
 options.
 
 ## Quick start
 
+The self-serve path: mint a key on the dashboard, export two env vars, sign a scan, push it.
+
 ```bash
 # 1. Scaffold a manifest for your project
 opencomplai init
@@ -64,10 +83,23 @@ opencomplai init
 # 2. Cross-check the manifest against your source tree
 opencomplai scan --manifest system-manifest.json --repo-root .
 
-# 3. Run the compliance gate (writes compliance-artifact.json)
-opencomplai check
+# 3. Get an API key from the dashboard's /connect page (Projects -> your
+#    project -> Connect), then export it alongside the dashboard's ingest URL
+export OPENCOMPLAI_API_KEY=ock_...
+export OPENCOMPLAI_DASHBOARD_URL=https://your-dashboard-host/api/ingest
+
+# 4. Run the compliance gate and sign the artifact (writes compliance-artifact.json)
+opencomplai check --sign
+
+# 5. Push the signed artifact to the dashboard
+opencomplai push
 ```
 
+Following this start-to-finish lands the scan on the dashboard's `/systems` page for that
+project. `/connect` also generates ready-to-paste GitHub Actions / GitLab CI snippets that
+wire the same two env vars into a pipeline — see
+[CI integration](https://docs.opencomplai.com/guides/ci-integration/).
+
 `opencomplai check` is the canonical CI gate. Its exit code is contractual:
 
 | Exit code | Meaning |
@@ -84,6 +116,10 @@ So you can wire it straight into CI:
 opencomplai check || exit $?
 ```
 
+To publish an Annex IV dossier instead of (or in addition to) a scan-status artifact, run
+`opencomplai docs generate --system-id ... --push` — same `OPENCOMPLAI_API_KEY` /
+`OPENCOMPLAI_DASHBOARD_URL` as `opencomplai push` above.
+
 ## Optional: AI intent analysis
 
 Install the [`opencomplai-ai`](https://pypi.org/project/opencomplai-ai/) plugin to unlock

opencomplai_cli-0.7.0/README.md

@@ -0,0 +1,117 @@
+# opencomplai-cli
+
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![PyPI](https://img.shields.io/pypi/v/opencomplai-cli.svg)](https://pypi.org/project/opencomplai-cli/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+
+The `opencomplai` command-line tool for EU AI Act compliance assessment. It scans your
+repository, classifies your AI system against the EU AI Act, and produces an auditable,
+CI-gateable compliance artifact.
+
+Built on [`opencomplai-core`](https://pypi.org/project/opencomplai-core/) — the same
+deterministic, rule-based risk engine, with a rich terminal UX.
+
+## Install
+
+```bash
+pip install opencomplai-cli
+```
+
+This pulls in `opencomplai-core[reports]` automatically. To install the full suite
+(engine + CLI) in one step, use the [`opencomplai`](https://pypi.org/project/opencomplai/)
+meta-package instead.
+
+## Core commands
+
+| Command | What it does |
+|---|---|
+| `opencomplai init` | Scaffold a `system-manifest.json` for your project |
+| `opencomplai scan` | Corroborate the manifest against your code and report discrepancies |
+| `opencomplai check` | Run the compliance gate and write `compliance-artifact.json` |
+| `opencomplai push` | Publish a signed artifact (scan status or Annex IV dossier) to the Premium Dashboard |
+| `opencomplai checker` | Run the interactive EU AI Act applicability checker |
+| `opencomplai gaps` | Print a per-article EU AI Act gap report (informational — never gates CI) |
+| `opencomplai recommend` | Write copy-paste remediation templates for Missing/Partial gap-report rows |
+| `opencomplai report` | Render a single shareable HTML/PDF compliance report |
+| `opencomplai eval` | Run safety, bias, and data-leakage pipeline evaluators |
+| `opencomplai validate-manifest` | Validate a `system-manifest.json` against the required schema |
+| `opencomplai serve` | Start a localhost-only scan dashboard (not Pro/SaaS) |
+| `opencomplai approve` | Mint a signed HITL approval token for a `HALTED_PENDING_REVIEW` system |
+| `opencomplai resume` | Resume a `HALTED_PENDING_REVIEW` system with a signed approval token |
+| `opencomplai verify-output` | Verify an AI output claim against ground-truth sources |
+| `opencomplai version` | Show the installed Opencomplai version |
+| `opencomplai info` | Show full package metadata (`pip show`-style, across the whole suite) |
+
+Also available as command groups (`opencomplai <group> --help` for their own subcommands):
+`docs` (Annex IV dossier generation), `risk` (risk classification), `sync` (metadata sync),
+`keys` (signing-key rotation), `ai` (optional AI-intent plugin configuration), `controls`
+(control-register status).
+
+Run `opencomplai --help` for the full command list, or `opencomplai <command> --help` for
+options.
+
+## Quick start
+
+The self-serve path: mint a key on the dashboard, export two env vars, sign a scan, push it.
+
+```bash
+# 1. Scaffold a manifest for your project
+opencomplai init
+
+# 2. Cross-check the manifest against your source tree
+opencomplai scan --manifest system-manifest.json --repo-root .
+
+# 3. Get an API key from the dashboard's /connect page (Projects -> your
+#    project -> Connect), then export it alongside the dashboard's ingest URL
+export OPENCOMPLAI_API_KEY=ock_...
+export OPENCOMPLAI_DASHBOARD_URL=https://your-dashboard-host/api/ingest
+
+# 4. Run the compliance gate and sign the artifact (writes compliance-artifact.json)
+opencomplai check --sign
+
+# 5. Push the signed artifact to the dashboard
+opencomplai push
+```
+
+Following this start-to-finish lands the scan on the dashboard's `/systems` page for that
+project. `/connect` also generates ready-to-paste GitHub Actions / GitLab CI snippets that
+wire the same two env vars into a pipeline — see
+[CI integration](https://docs.opencomplai.com/guides/ci-integration/).
+
+`opencomplai check` is the canonical CI gate. Its exit code is contractual:
+
+| Exit code | Meaning |
+|---|---|
+| `0` | PASS |
+| `1` | CONTROL_FAIL |
+| `2` | VALIDATION_FAIL |
+| `3` | POLICY_BLOCK |
+| `4` | TRAP_DETECTED |
+
+So you can wire it straight into CI:
+
+```bash
+opencomplai check || exit $?
+```
+
+To publish an Annex IV dossier instead of (or in addition to) a scan-status artifact, run
+`opencomplai docs generate --system-id ... --push` — same `OPENCOMPLAI_API_KEY` /
+`OPENCOMPLAI_DASHBOARD_URL` as `opencomplai push` above.
+
+## Optional: AI intent analysis
+
+Install the [`opencomplai-ai`](https://pypi.org/project/opencomplai-ai/) plugin to unlock
+the `--ai-intent` flag, which classifies how each AI callsite is actually used:
+
+```bash
+pip install opencomplai-ai
+opencomplai scan --ai-intent
+```
+
+## Documentation
+
+Full CLI reference and guides at **[docs.opencomplai.com](https://docs.opencomplai.com)**.
+
+## License
+
+AGPL-3.0-only. See [LICENSE](https://www.gnu.org/licenses/agpl-3.0).

{opencomplai_cli-0.5.0 → opencomplai_cli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opencomplai-cli"
-version = "0.5.0"
+version = "0.7.0"
 description = "Opencomplai command-line interface for EU AI Act compliance assessment"
 readme = "README.md"
 license = { text = "AGPL-3.0-only" }

{opencomplai_cli-0.5.0 → opencomplai_cli-0.7.0}/src/opencomplai_cli/__init__.py

@@ -1,6 +1,6 @@
 """Opencomplai CLI."""
 
-__version__ = "0.5.0"
+__version__ = "0.7.0"
 
 # Canonical project metadata — single source of truth for the `--version`
 # flag and the `opencomplai info` command. Mirrors the [project] table in

{opencomplai_cli-0.5.0 → opencomplai_cli-0.7.0}/src/opencomplai_cli/commands/dashboard.py

@@ -1,26 +1,25 @@
 """
 CLI dashboard sub-commands (C0.8).
 
-Subcommand: ``opencomplai dashboard enroll``
-    Opt an OSS install into the Premium Dashboard.
-
-    1. Validates the bootstrap token against the dashboard
-       ``POST /v1/admin/enroll`` (rate-limited, one-time-use).
-    2. Registers the install's signing key(s) with the tenant.
-    3. Writes an ``EgressConsent`` (``consent_scope=dashboard_metadata``) to
-       the OSS-side ledger.
-    4. Adds the dashboard endpoint to the local egress-proxy allowlist with a
-       per-endpoint policy reference.
-    5. Prints the dashboard URL and an audit-event hash the operator can verify.
-
-    Idempotent: re-running with the same tenant returns the existing enrollment
-    and emits no new ledger event.
+Subcommand: ``opencomplai dashboard enroll`` (hidden — see its own docstring)
+    Opt an OSS install into the Premium Dashboard via a one-time bootstrap
+    token. This is an operator path: the token has to come from somewhere,
+    and as of DG-11 nothing in this repo issues one outside a test (admin-api's
+    ``issue_bootstrap_token`` has zero non-test callers — no route, no web UI).
+    The self-serve onboarding path is the ``/connect`` page + an
+    ``OPENCOMPLAI_API_KEY`` (see ``opencomplai push`` / ``opencomplai docs
+    generate --push``), which needs none of this.
 
 Subcommand: ``opencomplai dashboard withdraw``
-    Remove dashboard enrollment for this install.
-
-    Emits a ``consent_revoked`` ledger event and removes the egress-proxy
-    allowlist entry within the same command run.
+    Clear this install's local enrollment state (egress-allowlist entry +
+    a ``consent_revoked`` ledger event) unconditionally. Also best-effort
+    notifies the dashboard's ``POST /v1/admin/withdraw`` when this install
+    can actually authenticate to it — that endpoint requires a tenant-scoped
+    service JWT (SEC-2) that a plain OSS install typically never has (it is
+    minted from ``enroll``'s OIDC client-credentials pair, and ``enroll`` is
+    the hidden/effectively-dead path described above). When no such token
+    can be produced, the remote call is skipped rather than sent bare and
+    guaranteed a 401 — see ``withdraw()``'s own docstring.
 """
 
 from __future__ import annotations
@@ -53,9 +52,7 @@ except ImportError:
     _console = _FallbackConsole()  # type: ignore[assignment]
     _err_console = _FallbackConsole()  # type: ignore[assignment]
 
-app = typer.Typer(
-    help="Premium Dashboard enrollment and withdrawal.", add_completion=False
-)
+app = typer.Typer(help="Premium Dashboard connection management.", add_completion=False)
 
 _OPENCOMPLAI_DIR = Path.home() / ".opencomplai"
 _CONFIG_FILE = _OPENCOMPLAI_DIR / "config.yaml"
@@ -177,7 +174,7 @@ def _post(url: str, payload: dict, token: str | None = None) -> tuple[int, dict]
 # ---------------------------------------------------------------------------
 
 
-@app.command("enroll")
+@app.command("enroll", hidden=True)
 def enroll(
     tenant: str = typer.Option(
         ..., "--tenant", help="Tenant ID from the dashboard signup"
@@ -192,10 +189,19 @@ def enroll(
     ),
 ) -> None:
     """
-    Enroll this install in the Opencomplai Premium Dashboard.
-
-    Validates the bootstrap token, registers signing keys, writes EgressConsent
-    to the local ledger, and adds the dashboard endpoint to the egress allowlist.
+    Operator path pending a UI to mint bootstrap tokens.
+
+    Enrolls this install in the Opencomplai Premium Dashboard by validating a
+    one-time bootstrap token, registering signing keys, writing EgressConsent
+    to the local ledger, and adding the dashboard endpoint to the egress
+    allowlist. Hidden from --help as of DG-11: nothing in this product issues
+    a bootstrap token outside a test today (admin-api's
+    ``issue_bootstrap_token`` has zero non-test callers), so this command has
+    no working entry point for a real customer to reach. It is kept, not
+    deleted, for the operator who already has -- or will eventually get a
+    console to mint -- a token. Everyone else wants the self-serve path:
+    an API key from ``/connect`` plus ``opencomplai push`` /
+    ``opencomplai docs generate --push``.
     """
     cfg = _load_config()
     install_id = cfg.get("install_id", "")
@@ -318,6 +324,41 @@ def enroll(
 # ---------------------------------------------------------------------------
 
 
+def _resolve_withdraw_token() -> str | None:
+    """
+    Best-effort bearer token for admin-api's ``POST /v1/admin/withdraw``
+    (SEC-2's ``PrincipalDep`` requires a tenant-scoped service JWT), mirroring
+    the CI connectors' own auth precedence
+    (``connectors/github_actions.py``/``gitlab_ci.py``): an operator-set
+    legacy bearer-token env var wins outright; otherwise this install's own
+    OIDC client-credentials pair (persisted locally by ``enroll`` — see
+    module docstring) is exchanged for a short-lived JWT.
+
+    Returns ``None`` — never raises — when neither path produces a token.
+    That is the *ordinary* outcome for the vast majority of installs, which
+    never went through ``enroll`` (it is hidden and has no working entry
+    point today): callers must treat it as "there is nothing to
+    authenticate a remote withdraw with," not as an error.
+    """
+    token = os.environ.get("OPENCOMPLAI_AUTH_TOKEN", "")
+    if token:
+        return token
+
+    client_id = _load_config().get("client_id", "")
+    client_secret = _read_client_secret() or ""
+    token_endpoint = os.environ.get("OPENCOMPLAI_TOKEN_ENDPOINT", "")
+    if not (client_id and client_secret and token_endpoint):
+        return None
+
+    from opencomplai_cli.oidc_client import OidcTokenError, acquire_token
+
+    try:
+        token, _ = acquire_token(token_endpoint, client_id, client_secret)
+    except OidcTokenError:
+        return None
+    return token
+
+
 @app.command("withdraw")
 def withdraw(
     tenant: str = typer.Option(..., "--tenant", help="Tenant ID to withdraw from"),
@@ -326,11 +367,28 @@ def withdraw(
         "--dashboard-url",
         help="Dashboard base URL (defaults to OPENCOMPLAI_DASHBOARD_URL env var)",
     ),
+    local_only: bool = typer.Option(
+        False,
+        "--local-only",
+        help=(
+            "Clear local state only — never attempt the remote "
+            "/v1/admin/withdraw call, even if a token is available."
+        ),
+    ),
 ) -> None:
     """
     Withdraw dashboard enrollment for this install.
 
-    Emits a consent_revoked ledger event and removes the egress allowlist entry.
+    Always clears local state: emits a consent_revoked ledger event and
+    removes the egress allowlist entry, in this same run. Also best-effort
+    notifies the dashboard, but only when a bearer token can actually be
+    produced for it (see _resolve_withdraw_token) — admin-api's
+    /v1/admin/withdraw requires an authenticated, tenant-scoped service JWT
+    (SEC-2), which most OSS installs have no way to mint. Sending the
+    request anyway would just guarantee a 401 that looks like a real
+    failure; skipping it prints a direct next step instead. A genuine
+    >=400 from the dashboard on a request that *did* carry a token is a
+    real rejection and still gets the loud error message.
     """
     cfg = _load_config()
     install_id = cfg.get("install_id", "")
@@ -344,37 +402,39 @@ def withdraw(
         "OPENCOMPLAI_DASHBOARD_URL", ""
     ).rstrip("/")
 
-    # --- Notify dashboard if URL is available ---
+    # --- Notify dashboard, only if we can actually authenticate to it ---
     # Best-effort and non-fatal by design (an offline install can still clear
-    # its own local state) — but a >=400 response is not the same as being
-    # unreachable: the dashboard *processed* the request and refused it, so
-    # egress consent almost certainly stays active server-side. That case
-    # gets its own louder message below rather than folding into the local
-    # "Withdrawal complete" line, which would otherwise claim a success that
-    # did not happen remotely (admin-api's /v1/admin/withdraw requires an
-    # authenticated, tenant-scoped service JWT as of SEC-2 — this CLI does
-    # not yet mint one, so every call currently gets 401; see HANDOFF.md).
-    # Vacuously true when no dashboard URL is configured at all — a purely
-    # local install has no remote consent state to fall out of sync with.
-    dashboard_notified = not base_url
-    if base_url:
-        try:
-            status, data = _post(
-                f"{base_url}/v1/admin/withdraw",
-                {"tenant_id": tenant, "install_id": install_id},
-            )
-            if status >= 400:
+    # its own local state). Three distinct outcomes below, each with its own
+    # message: (1) skipped because no token could be minted, or --local-only
+    # was passed, or no dashboard URL is configured at all -- the common
+    # case, not an error; (2) skipped because of an actual bug/note aside;
+    # (3) attempted with a real token and the dashboard rejected it (>=400)
+    # or was unreachable -- a genuine failure, kept loud so it isn't
+    # confused with (1)'s "there was never anything to try" case.
+    dashboard_notified = False
+    skipped_no_token = True
+    if base_url and not local_only:
+        token = _resolve_withdraw_token()
+        if token is not None:
+            skipped_no_token = False
+            try:
+                status, data = _post(
+                    f"{base_url}/v1/admin/withdraw",
+                    {"tenant_id": tenant, "install_id": install_id},
+                    token=token,
+                )
+                if status >= 400:
+                    _err_console.print(
+                        f"[red]Error:[/red] dashboard rejected the withdraw request "
+                        f"({status}: {data.get('message', data)}) — egress consent was "
+                        "NOT revoked server-side. Clearing local state only."
+                    )
+                else:
+                    dashboard_notified = True
+            except ConnectionError as exc:
                 _err_console.print(
-                    f"[red]Error:[/red] dashboard rejected the withdraw request "
-                    f"({status}: {data.get('message', data)}) — egress consent was "
-                    "NOT revoked server-side. Clearing local state only."
+                    f"[yellow]Warning:[/yellow] could not reach dashboard: {exc}"
                 )
-            else:
-                dashboard_notified = True
-        except ConnectionError as exc:
-            _err_console.print(
-                f"[yellow]Warning:[/yellow] could not reach dashboard: {exc}"
-            )
 
     # --- Emit consent_revoked ledger event ---
     from datetime import UTC, datetime
@@ -394,17 +454,26 @@ def withdraw(
     removed = allowlist.pop(key, None)
     _write_egress_allowlist(allowlist)
 
-    if removed:
-        if dashboard_notified:
+    if dashboard_notified:
+        if removed:
             _console.print(
                 f"[green]Withdrawal complete.[/green] Egress allowlist entry removed for tenant {tenant}."
             )
         else:
             _console.print(
-                f"[yellow]Local withdrawal complete[/yellow] — egress allowlist entry removed "
-                f"for tenant {tenant}, but the dashboard was not notified (see error above). "
-                "Server-side egress consent likely remains active."
+                f"[green]Withdrawal complete.[/green] No local egress allowlist entry was present for tenant {tenant}."
             )
+    elif skipped_no_token:
+        _console.print(
+            "[green]Local state cleared.[/green] Remote egress consent must be "
+            "revoked from the dashboard (Projects → Archive project)."
+        )
+    elif removed:
+        _console.print(
+            f"[yellow]Local withdrawal complete[/yellow] — egress allowlist entry removed "
+            f"for tenant {tenant}, but the dashboard was not notified (see error above). "
+            "Server-side egress consent likely remains active."
+        )
     else:
         _console.print(
             f"[dim]No egress allowlist entry found for tenant {tenant} — nothing to remove.[/dim]"

{opencomplai_cli-0.5.0 → opencomplai_cli-0.7.0}/src/opencomplai_cli/commands/push.py

@@ -31,7 +31,9 @@ from rich.markup import escape
 
 from opencomplai_cli.publish import (
     envelope_signature,
+    prepare_dossier_envelope,
     prepare_scan_status_artifact,
+    publish_dossier_envelope,
     publish_scan_status,
 )
 
@@ -150,4 +152,105 @@ def run_push(artifact_file: Path, *, env: dict[str, str] | None = None) -> int:
     return EXIT_PUBLISH_FAILED
 
 
-__all__ = ["EXIT_OK", "EXIT_PUBLISH_FAILED", "run_push"]
+def run_push_dossier(dossier_file: Path, *, env: dict[str, str] | None = None) -> int:
+    """
+    Read ``dossier_file`` (an ``AnnexIVDossier`` JSON -- e.g. the
+    ``dossier_<id>.json`` ``opencomplai docs generate`` writes locally),
+    shape it into a ``dossier_envelope``, and POST it to the dashboard
+    (DG-10).
+
+    Transliterated from ``run_push`` above: same file/env validation, same
+    ``http``-non-local warning, same auth model (``ock_`` API key, no
+    ``install_id``), same ``(0 success / 3 otherwise)`` return contract.
+    Two differences beyond the obvious (path, mapper, transport function):
+
+    * The envelope's own ``signature`` is always ``""``. Unlike a
+      ``ScanStatusArtifact``, an ``AnnexIVDossier``'s own ``signature``
+      field (when present) signs the *dossier bundle* under a scheme
+      unrelated to the ingest envelope's G-5 byte-identity check
+      (``envelope_signature``'s docstring) -- forwarding it would not
+      "sort of" verify, it would deterministically fail closed. A
+      key-authed push already attests via the API key itself, same as
+      scan status's own key-authed path (``dashboard_ingest.routes``).
+    * The error message on a missing file points at ``docs generate``
+      instead of ``check --sign``.
+    """
+    _env = env if env is not None else os.environ
+
+    if not dossier_file.exists():
+        err_console.print(f"[red]Error:[/red] dossier file not found: {dossier_file}")
+        err_console.print(
+            "Run [bold]opencomplai docs generate[/bold] first to produce one."
+        )
+        return EXIT_PUBLISH_FAILED
+
+    try:
+        raw_text = dossier_file.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        err_console.print(f"[red]Error:[/red] could not read {dossier_file}: {exc}")
+        return EXIT_PUBLISH_FAILED
+
+    try:
+        dossier: Any = json.loads(raw_text)
+    except json.JSONDecodeError as exc:
+        err_console.print(f"[red]Error:[/red] {dossier_file} is not valid JSON: {exc}")
+        return EXIT_PUBLISH_FAILED
+
+    if not isinstance(dossier, dict):
+        err_console.print(
+            f"[red]Error:[/red] {dossier_file} must contain a JSON object "
+            "(an AnnexIVDossier), not a "
+            f"{type(dossier).__name__}"
+        )
+        return EXIT_PUBLISH_FAILED
+
+    api_key = _env.get("OPENCOMPLAI_API_KEY", "")
+    dashboard_url = _env.get("OPENCOMPLAI_DASHBOARD_URL", "").rstrip("/")
+    if not api_key or not dashboard_url:
+        err_console.print(
+            "[red]Error:[/red] OPENCOMPLAI_API_KEY and OPENCOMPLAI_DASHBOARD_URL "
+            "must both be set."
+        )
+        return EXIT_PUBLISH_FAILED
+
+    parsed_url = urlparse(dashboard_url)
+    if parsed_url.scheme == "http" and parsed_url.hostname not in _LOCAL_HOSTNAMES:
+        err_console.print(
+            f"[yellow]Warning:[/yellow] OPENCOMPLAI_DASHBOARD_URL ({dashboard_url}) "
+            "uses plain http -- the API key will be sent unencrypted over the network. "
+            "Use https unless this is local development."
+        )
+
+    prepared = prepare_dossier_envelope(
+        dossier, commit_env=_env, repo_dir=dossier_file.resolve().parent
+    )
+
+    envelope = {
+        "system_id": prepared.get("system_id", "unknown"),
+        "artifact": prepared,
+        "signature": "",
+    }
+
+    status, data = publish_dossier_envelope(dashboard_url, api_key, envelope)
+
+    if status in (200, 201):
+        outcome = escape(
+            str(data.get("outcome", "accepted" if status == 201 else "replayed"))
+        )
+        content_hash = escape(str(data.get("content_hash", "")))
+        console.print(f"[green]Push {outcome}.[/green]")
+        console.print(f"  system_id:    {envelope['system_id']}")
+        console.print(f"  content_hash: {content_hash}")
+        console.print(f"\nDashboard: {dashboard_url}")
+        return EXIT_OK
+
+    err_console.print(f"[red]Push failed ({status}):[/red] {escape(str(data))}")
+    return EXIT_PUBLISH_FAILED
+
+
+__all__ = [
+    "EXIT_OK",
+    "EXIT_PUBLISH_FAILED",
+    "run_push",
+    "run_push_dossier",
+]