docs: explain author validation workflows

Author: zkwentz

.claude/skills/generate-openenv-env/assets/openenv_env_template/README.md

@@ -68,22 +68,22 @@ You can easily deploy your OpenEnv environment to Hugging Face Spaces using the
 # From the environment directory (where openenv.yaml is located)
 openenv push
 
-# Or specify options
-openenv push --namespace my-org --private
+# Or specify a target Space
+openenv push --repo-id my-org/__ENV_NAME__ --private
 ```
 
 The `openenv push` command will:
-1. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
-2. Prepare a custom build for Hugging Face Docker space (enables web interface)
-3. Upload to Hugging Face (ensuring you're logged in)
+1. Authenticate and prepare the exact Space revision
+2. Run strict publish validation in a dedicated Hugging Face Sandbox
+3. Add `.openenv/validation-report.json` and upload the validated revision
 
 ### Prerequisites
 
 - Authenticate with Hugging Face: The command will prompt for login if not already authenticated
 
 ### Options
 
-- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- Positional `directory`: Directory containing the OpenEnv environment (defaults to current directory)
 - `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
 - `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
 - `--private`: Deploy the space as private (default: public)

README.md

@@ -273,7 +273,8 @@ The OpenEnv CLI provides commands to manage environments:
 - **`openenv serve`** - Serve an environment locally with optional auto-reload
 - **`openenv build`** - Build the Docker image for an environment
 - **`openenv fork <space-id>`** - Fork a Space from HF Hub to your account
-- **`openenv validate`** - Validate an environment configuration
+- **`openenv validate`** - Validate locally or in a dedicated HF Sandbox; use
+  `--profile publish --remote` for the strict author gate
 
 ### Quick Start
 

docs/source/getting_started/contributing-envs.md

@@ -46,11 +46,23 @@ openenv push --private
 openenv push path/to/my_env
 ```
 
-That's it. The CLI validates your environment, stages the files, adds the Hugging Face Space frontmatter, enables the web interface, and uploads everything. Your environment will be live at
+That's it. The CLI authenticates with Hugging Face, prepares the exact Space
+revision, runs the strict `publish` profile on that snapshot in a dedicated HF
+Sandbox, adds an unofficial author report, and uploads the same revision. Your
+environment will be live at
 `https://huggingface.co/spaces/<your-username>/my_env`.
 
 > [!WARNING]
-> If you are getting errors on deployment, it is likely because the environment structure is not valid. Run `openenv validate --verbose` to see the errors. This checks for the required files (`openenv.yaml`, `pyproject.toml`, `server/app.py`) and validates the Dockerfile and entry points.
+> Run `openenv validate --profile publish --remote --verbose` before pushing.
+> Failed and incomplete criteria include configuration locations and suggested
+> fixes. A publish-ready environment also needs a `task.toml` requirements
+> envelope; `openenv init` creates a Harbor schema 1.1 starting point. Existing
+> environments created before this template must add truthful CPU, memory,
+> storage, GPU, and internet requirements rather than copying placeholders.
+
+The uploaded `.openenv/validation-report.json` records author validation; it is
+not certification. A future Hub service will run broader security,
+reproducibility, artifact, and training-value checks independently.
 
 ## 2. Fork Someone Else's Environment
 

docs/source/getting_started/environment-builder.md

@@ -74,7 +74,10 @@ openenv init my_env
 openenv init my_env --output-dir /Users/you/envs
 ```
 
-The command creates a fully-typed template with `openenv.yaml`, `pyproject.toml`, `uv.lock`, Docker assets, and stub implementations. If you're working inside this repo, move the generated folder under `envs/`.
+The command creates a fully-typed template with `openenv.yaml`, a Harbor schema
+1.1 `task.toml` resource envelope, `pyproject.toml`, `uv.lock`, Docker assets,
+and stub implementations. If you're working inside this repo, move the
+generated folder under `envs/`.
 
 Typical layout:
 
@@ -85,6 +88,7 @@ my_env/
 ├── client.py
 ├── models.py
 ├── openenv.yaml
+├── task.toml
 ├── pyproject.toml
 ├── uv.lock
 └── server/
@@ -318,6 +322,7 @@ From the environment directory:
 cd envs/my_env
 openenv build          # Builds Docker image (auto-detects context)
 openenv validate --verbose
+openenv validate --profile publish --remote --output validation.json
 ```
 
 `openenv build` understands both standalone environments and in-repo ones. Useful flags:
@@ -327,7 +332,12 @@ openenv validate --verbose
 - `--dockerfile` / `--context`: custom locations when experimenting
 - `--no-cache`: force fresh dependency installs
 
-`openenv validate` checks for required files, ensures the Dockerfile/server entrypoints function, and lists supported deployment modes. The command exits non-zero if issues are found so you can wire it into CI.
+`openenv validate` always uses the shared validation report. The `static` and
+`runtime` profiles support fast iteration; `publish` is strict and exits
+non-zero when a blocking check fails, errors, or cannot run. `--remote` runs
+the environment in a dedicated HF Sandbox. Human output includes typed fixes,
+while `--json` or `--output` provides the same structured report for agents and
+CI.
 
 ### 8. Push & Share with `openenv push`
 
@@ -361,7 +371,12 @@ Key options:
 - `--env-var/-e KEY=VALUE`: set a public Space variable (repeatable); overrides matching keys from `variables:` in `openenv.yaml`
 - `--secret KEY=VALUE`: set a private Space secret (repeatable); value is never logged
 
-The command validates your `openenv.yaml`, injects Hugging Face frontmatter when needed, and uploads the prepared bundle.
+For Hub pushes, the command prepares the bundle (including Hugging Face
+frontmatter), validates that exact snapshot remotely, and uploads it together
+with `.openenv/validation-report.json`. That versioned report is unofficial
+author evidence. When deployed, the Hub's broader certification suite will
+publish an independent result rather than trusting or overwriting the author
+report.
 Space variables and secrets are only applied on direct Hugging Face Space pushes;
 they are not available for `--registry`, and they cannot be staged through
 `--create-pr`.

docs/source/reference/cli.md

@@ -48,14 +48,24 @@ openenv validate path/to/env --profile static
 openenv validate path/to/env --profile runtime --json
 openenv validate --url http://127.0.0.1:8000 --profile runtime --json
 openenv validate path/to/env --profile full --output validation.json
+openenv validate path/to/env --profile publish --remote --output validation.json
 ```
 
 `static` checks source and packaging, `runtime` adds a launched or connected
 server, and `full` records every policy criterion while marking unavailable
-remote capabilities as skipped. Local reports never claim official
-certification. Automatic local launch executes the environment checkout as the
-current user and is intended only for trusted development source; use `--url`
-for a server you already isolated.
+remote capabilities as skipped. `publish` runs the runtime check set as a
+strict author gate: every blocking criterion must pass, so blocking skips are
+reported as incomplete and exit non-zero. Reports include typed diagnostics,
+repository-relative locations, display-only remediation, and safe evidence
+with `--verbose`.
+
+`--remote` uploads the environment revision and the initiating validator source
+to a new dedicated Hugging Face Sandbox. The HF token authorizes Sandbox
+creation but is not forwarded into the workload. The returned report uses the
+same schema and remains unofficial; it never claims Hub certification.
+Automatic local launch executes the checkout as the current user and is only
+for trusted development source. Use `--url` for a server you already isolated,
+or `--remote` to isolate source execution.
 
 This command intentionally targets the served OpenEnv spec. Shared reports
 record spec, adapter, and execution-model provenance, but `openenv validate`
@@ -66,6 +76,12 @@ task workflow is tracked in [issue #898](https://github.com/huggingface/OpenEnv/
 
 ## `openenv push`
 
+Hub pushes automatically require a passing remote `publish` report. The CLI
+adds a portable copy to `.openenv/validation-report.json` in the same uploaded
+revision. This is author evidence for debugging and automation, not the richer
+independent certification report that the planned Hub validation service will
+produce.
+
 [[autodoc]] openenv.cli.commands.push.push
 
 ## `openenv serve`

src/openenv/cli/commands/push.py

@@ -723,9 +723,12 @@ def push(
     Push an OpenEnv environment to Hugging Face Spaces or a custom Docker registry.
 
     This command:
-    1. Validates that the directory is an OpenEnv environment (openenv.yaml present)
-    2. Builds and pushes to Hugging Face Spaces or custom Docker registry
-    3. Optionally enables web interface for deployment
+    1. Prepares the exact Hub upload and validates it in a dedicated HF Sandbox
+    2. Requires every blocking publish criterion to pass
+    3. Uploads a portable, unofficial `.openenv/validation-report.json`
+
+    Custom registry pushes run the same strict publish profile locally before
+    building. The versioned Hub report is author evidence, not certification.
 
     The web interface is enabled by default when pushing to HuggingFace Spaces,
     but disabled by default when pushing to a custom Docker registry.
@@ -738,7 +741,6 @@ def push(
         $ openenv push
 
         # Push to HuggingFace repo and open a Pull Request
-        $ openenv push my-org/my-env --create-pr
         $ openenv push --repo-id my-org/my-env --create-pr
 
         # Push to HuggingFace without web interface

src/openenv/cli/commands/validate.py

@@ -104,7 +104,8 @@ def validate(
     versioned runtime API contract and returns a criteria-based JSON report.
     Every profile emits the RFC 008 shared report. The publish profile is a
     strict release gate: blocking skipped checks are incomplete and exit
-    non-zero.
+    non-zero. `--remote` runs the same plan in a fresh dedicated Hugging Face
+    Sandbox and returns the same report schema.
     Reports identify the served OpenEnv spec and pinned adapter; external task
     package formats are intentionally outside this command's dispatch surface.
     Automatic runtime launch is intended for trusted local source; connect to
@@ -129,6 +130,9 @@ def validate(
 
         # Run every locally available check and record remote-only skips
         $ openenv validate envs/echo_env --profile full --output report.json
+
+        # Run the strict author gate remotely and save its structured guidance
+        $ openenv validate envs/echo_env --profile publish --remote --output report.json
         ```
     """
     runtime_target = url

src/openenv/cli/templates/openenv_env/README.md

@@ -68,22 +68,22 @@ You can easily deploy your OpenEnv environment to Hugging Face Spaces using the
 # From the environment directory (where openenv.yaml is located)
 openenv push
 
-# Or specify options
-openenv push --namespace my-org --private
+# Or specify a target Space
+openenv push --repo-id my-org/__ENV_NAME__ --private
 ```
 
 The `openenv push` command will:
-1. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
-2. Prepare a custom build for Hugging Face Docker space (enables web interface)
-3. Upload to Hugging Face (ensuring you're logged in)
+1. Authenticate and prepare the exact Space revision
+2. Run strict publish validation in a dedicated Hugging Face Sandbox
+3. Add `.openenv/validation-report.json` and upload the validated revision
 
 ### Prerequisites
 
 - Authenticate with Hugging Face: The command will prompt for login if not already authenticated
 
 ### Options
 
-- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- Positional `directory`: Directory containing the OpenEnv environment (defaults to current directory)
 - `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
 - `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
 - `--private`: Deploy the space as private (default: public)