Native input editing

Choose a build and import inputs

Sign in at /login with Continue with Google. In the signed-in workspace, choose a build advertised by the current catalog and import your native input files. Keep the exact build identity with the saved package and scenario. The build guide distinguishes the default fixed-filter build from the opt-in saved JSON output-plan build.

Native files remain authoritative. Unknown JSON fields, supporting files, empty files and untouched bytes are preserved. GUI forms project the mapped parts of those files; they do not replace native content with a second workspace format.

GUI and Source

1. Open the farm or a named scenario and choose a section or native file.
2. Use GUI where the schema maps a concrete native file and JSON Pointer. Use Source for exact JSON/CSV text, unknown structures, unsupported controls or unsafe numbers.
3. Switch between GUI and Source within the workspace to inspect the same retained draft. Read Structural / schema checks, including missing-metadata notices.
4. Choose Review & save, inspect the server preview and exact file diffs, enter a reason, then choose Save reviewed changes.
5. Inspect the atomic receipt and resulting revision. Check saved inputs is a separate check of saved state.

The current bundle has no reviewed CSV grid identity. CSV Source remains supported. Explicit CLI/API CSV keys are caller-supplied addresses checked against actual headers and unique rows; they are not invented scientific metadata. CSV cells remain strings, and key columns cannot be edited as ordinary cells.

Source can retain malformed or scientifically invalid drafts with failed diagnostics. Saving a draft is not an assertion of scientific validity. Metadata that the schema does not supply remains missing. Navigation or reload is not a promise of draft recovery; review and save work you intend to retain.

Revision checks

Every new conditional batch names a positive expected_revision, an exact expected_binding_sha256, original SHA-256 file expectations, ordered operations, a reason and a manual channel. A null file expectation means a new file must be absent. JSON replacement/removal also names the original value; null differs from absence and booleans differ from numbers. Raw replacement/deletion requires expected_sha256.

The following is an illustrative request shape, not a recommended herd size or a scientific default. Replace the revision, hashes, original value and proposed value with inspected and reviewed data from your own native file. Use the actual package-relative file path and concrete pointer.

{
  "expected_revision": 1,
  "expected_binding_sha256": "REPLACE_WITH_INSPECTED_BUILD_BINDING_SHA256",
  "file_expectations": [
    {
      "file": "input/data/animal/example_freestall_animal.json",
      "sha256": "REPLACE_WITH_ORIGINAL_FILE_SHA256"
    }
  ],
  "operations": [
    {
      "op": "replace",
      "file": "input/data/animal/example_freestall_animal.json",
      "path": "/herd_information/herd_num",
      "expected": 100,
      "value": 120
    }
  ],
  "reason": "Reviewed native input change",
  "channel": "api"
}

Retain an Idempotency-Key and the exact approved request for retries. Repeating the same key and request returns the original receipt and result revision, even if the head later changes. A changed request with that key conflicts. Stale revisions, wrong build/file/value expectations and invalid operations publish no part of the batch.

If the GUI shows Saved revision conflict, inspect the current saved files with Compare current saved revision and reconcile deliberately. Drafts remain intact. Do not overwrite a new head merely to dismiss a conflict. The receipt identifies source/result revisions, the build binding, changed files and diagnostics.

Local CLI workflow

Use Python 3.12 or 3.13 from the repository's backend directory. These standard-library commands need no account, database service, cloud credentials, LLM or model execution. farm.sqlite, input folders and destination names below are examples you choose; the local database retains private native files and revision history.

python -m app.model_cli catalog
python -m app.model_cli select --model-version-id rufas-1.0.5-freestall-v1
python -m app.model_cli --workspace farm.sqlite import --source native-inputs --model-version-id rufas-1.0.5-freestall-v1
python -m app.model_cli --workspace farm.sqlite inspect
python -m app.model_cli --workspace farm.sqlite read --document input/data/animal/example_freestall_animal.json --pointer /herd_information/herd_num
python -m app.model_cli --workspace farm.sqlite validate --revision 1 --request-file reviewed-changes.json
python -m app.model_cli --workspace farm.sqlite edit --request-file reviewed-changes.json --idempotency-key reviewed-input-edit-01
python -m app.model_cli --workspace farm.sqlite diff --from-revision 1 --to-revision 2
python -m app.model_cli --workspace farm.sqlite validate --revision 2
python -m app.model_cli --workspace farm.sqlite export --revision 2 --destination farm-r2.zip

Save the reviewed request as reviewed-changes.json. Inspect its actual revision/binding/file hashes first. Import accepts a native folder or bounded ZIP. A later import requires both --replace and --expected-revision N. Export creates a new destination and refuses overwriting. Global flags such as --workspace, --remote and --scenario-id precede the command. Use each command's --help for options.

Local validate --request-file previews without publication. Local validation reports syntax, supported declared rules and coverage gaps; it neither runs native audit nor establishes simulation readiness. Read the report even after a successful command exit.

Remote CLI and public API

Remote work uses the same authenticated public gateway under /api/platform. Set SIMULATE_FARM_BASE_URL to the HTTPS application origin and provide SIMULATE_FARM_API_KEY through your environment or secret manager. Never paste a key into a command or commit it. Obtain the personal key through the signed-in application; request catalog:read, inputs:read and inputs:write for this editing workflow. Existing legacy keys do not silently gain those permissions. Changing scopes requires revocation and reissuance under the one-active-key rule.

Replace EXISTING_SCENARIO_ID with an owned scenario in your region. Fetch the deployment's catalog first; its binding can differ from the local development catalog.

python -m app.model_cli --remote catalog
python -m app.model_cli --remote --scenario-id EXISTING_SCENARIO_ID inspect
python -m app.model_cli --remote --scenario-id EXISTING_SCENARIO_ID validate --revision 1 --request-file reviewed-changes.json
python -m app.model_cli --remote --scenario-id EXISTING_SCENARIO_ID edit --request-file reviewed-changes.json --idempotency-key reviewed-input-edit-01

The matching public API publishes conditional batches at POST /api/platform/input-packages/{id}/changes or POST /api/platform/file-scenarios/{id}/changes; append /preview for review without publication. Use the request shape above and the Idempotency-Key header. Read authenticated /api/platform/client-capabilities and catalog capabilities for effective scopes and supported contracts. Backend identity headers and unrestricted server credentials are not client interfaces.

HTTPS is required remotely. --allow-local permits HTTP only to loopback for development; redirects are refused. Uncertain network outcomes do not trigger automatic mutation retries. Inspect saved state or repeat the exact retained request and key. Remote editing/validation does not submit a simulation.

Explicit execution

Save, portable validation and output-plan preview are separate from native audit and simulation. With all drafts saved, choose Run, review the exact scenario revision, then Confirm and run. The supported GUI flow checks action availability, preflights saved inputs, freezes a snapshot, completes native audit where required, and requests simulation only if its admission checks pass. If you are editing a baseline, Create run scenario preserves the farm version used for the run.

The input CLI above does not execute simulations. The existing public Python client, examples/run_rufas.py, exposes separate audit-files, run-files and resume-files actions on explicit snapshot/run identities. From the backend directory, use python ../examples/run_rufas.py --help to inspect its commands; audit must provide the evidence required for that exact snapshot before simulation admission. Run submission and result reading require their additional runs:submit and runs:read scopes.

A native audit does not certify unrestricted inputs. An unavailable catalog/region action stays unavailable. Changing inputs or a saved output filter requires fresh snapshot/audit evidence. Read saved JSON output plans and results next.