Git context workflow

Initial setup

Use an existing repo or a dedicated directory:

querio init Acme --git --repo . --no-input
querio init Acme --git --repo ../acme-context --no-input

Choose one, not both. Inside an existing repo, even from a subdirectory, init uses its root. Outside a repo it creates one at the target directory. It seeds missing memory and bundled skill files locally and writes root querio.toml. Existing seed files and unrelated TOML settings survive; TOML formatting and comments are rewritten. No files are staged, committed, uploaded, or promoted. Git init provisions a changeset-mode hosted workspace without seeding hosted context. Its operational root config remains separate from the repo selection config.

Use --local-only for offline local seeding with no login or network calls. Later rerun the same command without --local-only to provision and select the hosted workspace. A request ID saved in the local TOML is reused to avoid duplicate provisioning. After a failed provisioning request, keep that ID and workspace name unchanged.

Use repeated --include and --exclude flags to populate TOML with your selection. Defaults include memory/**, skills/**, and automations/**, not the root config itself. Existing selection settings are retained unless explicitly replaced. A terminal prompts for Git/non-Git and selection settings; --no-input disables prompts. Noninteractive invocations default to non-Git for compatibility; use an explicit mode in automation.

querio init Acme --no-git --no-input retains the hosted workflow and does not write local files. Its context selection is stored in hosted querio.toml.

Prerequisites

For an existing workspace, select Changeset file mode in Workspace settings before using this workflow. New workspaces provisioned by init --git already use that mode. Running canonical environments keep their existing files; close them deliberately rather than assuming the setting moves them. Use the CLI's normal login and workspace selection. Local upload requires Git installed locally, but no Git remote, forge credentials, or push.

Git upload requires workspace file write permission. Promotion requires workspace file write and delete permissions because it can remove previously managed source files. Patch export and status require workspace file read permission. Your CI principal must have the appropriate permission. Promotion relies on your change-management process for approval; Querio does not verify PRs or test results.

Configure and commit source

Add a querio.toml to the repository:

[context]
include = ["context/**", "notebooks/approved/*.py"]
exclude = ["context/private/**"]

Paths stay repository-relative; there is no required context directory layout. Includes and excludes are relative globs, exclusions win, and ** matches zero or more directories. Only committed selected files are uploaded. Git's ignore rules do not remove already committed files. Selection is not secret detection: review the upload before sending it.

The configuration is read from the selected commit, not from uncommitted local files. It is recorded by path and SHA-256; the configuration file itself is uploaded only if selected by the patterns. The root .querio directory is reserved for runtime storage. Selected submodules are unsupported. Relative in-scope symlinks and executable bits are preserved. Transfers are limited to 64 MiB of JSON including base64 encoding and metadata; the CLI also limits selected raw content to 48 MiB.

git add querio.toml context
git commit -m 'Prepare context'
querio git upload --repository my-team/context --dry-run
querio git upload --repository my-team/context

--repository is a stable provenance label, not a clone URL or credential. It can be omitted when the committed TOML contains [context].repository, which Git init seeds automatically. Use the same identity in developer and CI invocations. --repo selects a local checkout, --ref selects a commit/ref (default HEAD), and --config selects the committed config path (default querio.toml). Dry-run is offline and prints selected paths, not their contents.

Upload returns {"version":"..."}. It neither creates a working copy nor promotes canonical. A local-only commit is sufficient. Source metadata is a caller assertion, not cryptographic verification that the uploaded files belong to a remote repository.

Run and resume a working copy

querio git checkout <version>
querio execution-environment create --changeset <returned-id> --json

Open notebook sessions using the returned environment ID as described in the Resource API guide. The uploaded snapshot is immutable; the selected working copy is editable. Stored edits survive compute shutdown. Close the old environment before attaching the same stored working copy to replacement compute. Each concurrent environment needs its own working copy.

querio execution-environment close <environment-id>
querio execution-environment create --changeset <same-working-copy-id> --json

Closing compute does not discard the stored files. querio git status lists working copies and the current canonical version. querio git status <working-copy-id> inspects stored edits and source Git provenance without starting compute. Inside a selected session, existing querio changes status and querio changes diff inspect edits. For Git-backed copies, a difference between source base and the mixed canonical directory is not a requirement to rebase before exporting.

Return selected edits locally

Pause native writers before exporting. Export captures current edits and returns only explicitly selected changed file paths:

querio git patch <working-copy-id> \
  --path context/revenue.sql \
  --path notebooks/approved/revenue.py > changes.patch

Check that export succeeded before applying the output. --json returns base64 patch content instead of raw patch bytes. Binary replacements, additions, deletions, symlinks, and executable-mode changes are supported. Empty directories are not represented by Git patches. Selecting only part of a file/directory type transition can be invalid; select all changed files needed to form a valid tree.

The patch is against the uploaded commit's selected files. Apply it in the original repository and reconcile local divergence with normal Git tools:

git apply --check changes.patch
git apply changes.patch
git diff
git add context/revenue.sql notebooks/approved/revenue.py
git commit -m 'Review hosted edits'

Export does not approve or promote anything. An output can be exported simply for further local work. Unselected outputs remain stored. Git-backed working copies retain their original Git base; reconcile locally and upload a new commit rather than using Querio's base-update operation. Commit author information remains in local Git; Querio records authenticated upload/export/promotion actors. The CLI does not commit, push, or open PRs in this initial workflow.

Promote from CI

Observe canonical before starting the promotion attempt:

querio git status --json
querio git upload --repository my-team/context --ref HEAD --json
querio git promote <uploaded-version> --expected-canonical <observed-canonical-version>

CI can promote a commit never previously run in Querio. It uploads the selected committed files itself; Querio does not fetch from a forge. A stale canonical precondition returns a conflict. Do not automatically substitute a newer canonical version and retry an older deployment; re-evaluate ordering in CI.

Promotion updates the tracked Git-managed file set. Previously managed files absent from the incoming snapshot are removed. Unrelated files and outputs survive. An incoming path that conflicts with differing unmanaged content is rejected rather than overwritten; resolve that collision explicitly. In particular, the mounted workspace's own querio.toml may differ from a repository's selection config: do not assume a broad include can replace it.

New default changesets start from the promoted source snapshot. Existing working copies and running environments are not switched. Canonical direct file writes do not alter the promoted source snapshot used for new default changesets. Current Context screens still read the mounted canonical directory; they are not a new Git review UI.

NFS publication remains file-by-file, not an atomic filesystem transaction. A failure can leave partial mounted-directory updates; the promoted source pointer advances only after successful application. Do not treat a failed request as approval or blindly retry. Inspect status and files before reconciling. Uploads and mutations are not automatically retried; a lost response can follow a successful operation. There is no automatic snapshot/working-copy garbage collection.

GitHub/other forge integration, generalized context discovery/indexing, and notebook-file serialization are separate work. This workflow transfers selected repository files; it does not automatically convert app notebook records into files.